From a8755357613e32e65600b9ebf4d6650e50dbdbb2 Mon Sep 17 00:00:00 2001
From: "grafana-delivery-bot[bot]"
 <132647405+grafana-delivery-bot[bot]@users.noreply.github.com>
Date: Thu, 14 Nov 2024 11:01:40 -0500
Subject: [PATCH] [v10.4.x] Docs: Add canvas custom images and icon guidance
 (#96466)

Co-authored-by: Drew Slobodnjak <60050885+drew08t@users.noreply.github.com>
Co-authored-by: Isabel Matwawana <76437239+imatwawana@users.noreply.github.com>
---
 .../visualizations/canvas/index.md            | 37 ++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/docs/sources/panels-visualizations/visualizations/canvas/index.md b/docs/sources/panels-visualizations/visualizations/canvas/index.md
index 2e2b154d3d6..49d2b431957 100644
--- a/docs/sources/panels-visualizations/visualizations/canvas/index.md
+++ b/docs/sources/panels-visualizations/visualizations/canvas/index.md
@@ -81,7 +81,23 @@ The rectangle element lets you add a basic rectangle to the canvas. A rectangle
 
 ### Icon
 
-The icon element lets you add a supported icon to the canvas. Icons can have their color set based on thresholds / value mappings.
+The icon element lets you add a supported icon to the canvas. Icons can have their color set based on thresholds or value mappings.
+
+#### Add a custom icon
+
+You can add a custom icon by referencing an SVG file. To add a custom icon, follow these steps:
+
+1. Under **Icon > SVG Path**, if it's not already selected, select **Fixed** as your file source.
+1. Click **Select a value** in the field below.
+1. In the dialog box that opens, click the **URL** tab.
+1. Enter the URL in the field below the **URL** tab.
+
+   {{< figure src="/media/docs/grafana/panels-visualizations/screenshot-canvas-custom-image-v11.3.png" max-width="300px" alt="Add a custom image URL" >}}
+
+1. Click **Select**.
+1. (Optional) Add a background image to your icon with the **Background (icon)** option by following the steps to [add a custom image](#add-custom-images-to-elements).
+
+If you don't have an SVG file, you can use a rectangle element instead of an icon and set its background image to an image file type. To add a custom image for another element type, follow the steps to [add a custom image](#add-custom-images-to-elements).
 
 ### Server
 
@@ -101,6 +117,25 @@ A button click will only trigger an API call when [inline editing](#inline-editi
 
 {{< docs/play title="Canvas Visualization: Buttons" url="https://play.grafana.org/d/c9ea65f5-ed5a-45cf-8fb7-f82af7c3afdf/" >}}
 
+## Add custom images to elements
+
+You can add custom background images to all elements except **Button** by referencing an image URL.
+The image must be hosted at a URL that allows requests from your Grafana instance.
+
+To upload a custom image, follow these steps:
+
+1. Under **Background (\<ELEMENT TYPE\>)**, if it's not already selected, select **Fixed** as your image source.
+
+   {{< figure src="/media/docs/grafana/panels-visualizations/screenshot-canvas-custom-image-src-v11.3.png" max-width="300px" alt="Custom image source selection" >}}
+
+1. Click **Select a value** in the field below.
+1. In the dialog box that opens, click the **URL** tab.
+1. Enter the URL in the field below the **URL** tab.
+
+   {{< figure src="/media/docs/grafana/panels-visualizations/screenshot-canvas-custom-image-v11.3.png" max-width="300px" alt="Add a custom image URL" >}}
+
+1. Click **Select**.
+
 ## Connections
 
 When building a canvas, you can connect elements together to create more complex visualizations. Connections are created by dragging from the connection anchor of one element to the connection anchor of another element. You can also create connections to the background of the canvas. Connection anchors are displayed when you hover over an element and inline editing is turned on. To remove a connection, simply click on the connection directly and then press the "Delete" or "Backspace" key.