Menu
Grafana Cloud

Canvas

Canvases combine the power of Grafana with the flexibility of custom elements. They are extensible visualizations that allow you to add and arrange elements wherever you want within unstructured static and dynamic layouts. This lets you design custom visualizations and overlay data in ways that aren’t possible with standard Grafana visualizations, all within the Grafana UI.

If you’ve used popular UI and web design tools, then designing canvases will feel very familiar. With all of these dynamic elements, there’s almost no limit to what a canvas can display.

Note

We’d love your feedback on the canvas visualization. Please check out the open Github issues and submit a new feature request as needed.

Supported data formats

The canvas visualization is unique in that it doesn’t have any specific data requirements. You can even start adding and configuring visual elements without providing any data. However, any data you plan to consume should be accessible through supported Grafana data sources and structured in a way that ensures smooth integration with your custom elements.

If your canvas is going to update in real time, your data should support refreshes at your desired intervals without degrading the user experience.

You can tie Elements and Connections to data through options like text, colors, and background pattern images, etc. available in the canvas visualization.

Elements

Elements are the basic building blocks of a canvas and they help you visualize data with different shapes and options. You can rotate and move elements around the canvas. When you move elements, snapping and alignment guides help you create more precise layouts.

Note

Element snapping and alignment only works when the canvas is not zoomed in.

When you select an element that you’ve added to a canvas, you can access editing options for it that are dependent on the element type. The following sections describe the different elements available.

Basic shapes

A basic shape element can display text (both fixed and field data) and its background color can be changed based on data thresholds. You can add the following basic shapes to a canvas:

  • Cloud
  • Ellipse
  • Parallelogram
  • Rectangle
  • Triangle

Metric value

The metric value element lets you easily select the data you want to display on a canvas. This element has a unique “edit” mode that can be triggered either through the context menu “Edit” option or by double clicking. When in edit mode you can select which field data that you want to display.

Metric value element demo

Text

The text element lets you easily add text to the canvas. The element also supports an editing mode, triggered via either double clicking or the edit menu option in the context menu.

Text element demo

Icon

The icon element lets you add a supported icon to the canvas. Icons can have their color set based on thresholds / value mappings.

Server

The server element lets you easily represent a single server, a stack of servers, a database, or a terminal. Server elements support status color, bulb color, and a bulb blink rate all configurable by fixed or field values.

Canvas server element
Canvas server element

Button

The button element lets you add a basic button to the canvas. Button elements support triggering basic, unauthenticated API calls. API settings are found in the button element editor. You can also pass template variables in the API editor.

Note

A button click will only trigger an API call when inline editing is disabled.
Canvas button element demo

Give it a try using Grafana Play

With Grafana Play, you can explore and see how it works, learning from practical examples to accelerate your development. This feature can be seen on Canvas Visualization: Buttons.

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.

Canvas connections demo

Adjust connectors

You can adjust connectors, adding angles to them, to fit the canvas you’re working in. When you move connected elements, the connector resizes to fit the space. To adjust a connector, click it to display the midpoint controls and move those as needed. To make a connector a straight line again, move the midpoint back until the midpoint controls disappear.

If you move a connector so that it’s almost a right angle or a straight line, the connector snaps into that angle or into a straight line.

Style connectors

You can set the size, color, direction, and style of connections based on fixed or field values. To do so, enter into panel edit mode, select the connection, and modify the connection’s properties in the panel editor.

Canvas service graph
Canvas service graph

Canvas editing

Inline editor

You can edit your canvas inline while in the context of dashboard mode.

Inline editor demo

Pan and zoom

You can enable panning and zooming in a canvas. This allows you to both create and navigate more complex designs.

Note

Canvas pan and zoom is currently in public preview. Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available. Enable the canvasPanelPanZoom feature toggle in Grafana to use this feature. Contact Grafana Support to enable this feature in Grafana Cloud.
Canvas pan zoom control
Canvas pan and zoom enablement video

Infinite panning

You can enable infinite panning in a canvas when pan and zoom is enabled. This allows you to pan and zoom the canvas and uncover larger designs.

Note

Infinite panning is an experimental feature that may not work as expected in all scenarios. For example, elements that are not top-left constrained may experience unexpected movement when panning.

Context menu

The context menu lets you perform common tasks quickly and efficiently. Supported functionality includes opening / closing the inline editor, duplicating an element, deleting an element, and more.

The context menu is triggered by a right click action over the panel / over a given canvas element. When right clicking the panel, you are able to set a background image and easily add elements to the canvas.

Canvas panel context menu
Canvas panel context menu

When right clicking an element, you are able to edit, delete, duplicate, and modify the element’s layer positioning.

Canvas element context menu
Canvas element context menu

Canvas options

Inline editing

The inline editing toggle lets you lock or unlock the canvas. When turned off the canvas becomes “locked”, freezing elements in place and preventing unintended modifications.

Inline editing toggle demo

Canvases support data links for all elements except drone and button elements. You can add a data link by following these steps:

  1. Enable inline editing.

  2. Click the element you to which you want to add the data link.

  3. In either the inline editor or panel editor, expand the Selected element editor.

  4. Scroll down to the Data links section and expand it.

  5. Click Add link.

  6. In the dialog box that opens, enter a Title. This is a human-readable label for the link, which will be displayed in the UI.

  7. Enter the URL or variable to which you want to link.

    To add a data link variable, click in the URL field and enter $ or press Ctrl+Space or Cmd+Space to see a list of available variables.

  8. If you want the link to open in a new tab, toggle the Open in a new tab switch.

  9. Click Save to save changes and close the dialog box.

  10. Disable inline editing.

If you add multiple data links, you can control the order in which they appear in the visualization. To do this, click and drag the data link to the desired position.

You can configure a canvas data link to open with a single click on the element. To enable this feature, follow these steps:

  1. Enable inline editing.
  2. Click the element to which you want to add the data link.
  3. In either the inline editor or panel editor, expand the Selected element editor.
  4. Scroll down to the Data links section and expand it.
  5. In the One-click section, choose Link.
  6. Disable inline editing.

The first data link in the list will be configured as your one-click data link. If you want to change the one-click data link, simply drag the desired data link to the top of the list.

Panel options

In the Panel options section of the panel editor pane, set basic options like panel title and description, as well as panel links. To learn more, refer to Configure panel options.

Standard options

Standard options in the panel editor pane let you change how field data is displayed in your visualizations. When you set a standard option, the change is applied to all fields or series. For more granular control over the display of fields, refer to Configure overrides.

OptionDescription
UnitChoose which unit a field should use.
Min/MaxSet the minimum and maximum values used in percentage threshold calculations or leave these field empty for them to be calculated automatically.
Field min/maxEnable Field min/max to have Grafana calculate the min or max of each field individually, based on the minimum or maximum value of the field.
DecimalsSpecify the number of decimals Grafana includes in the rendered value.
Display nameSet the display title of all fields. You can use variables in the field title.
Color schemeSet single or multiple colors for your entire visualization.
No valueEnter what Grafana should display if the field value is empty or null. The default value is a hyphen (-).

To learn more, refer to Configure standard options.

Thresholds

A threshold is a value or limit you set for a metric that’s reflected visually when it’s met or exceeded. Thresholds are one way you can conditionally style and color your visualizations based on query results.

For each threshold, set the following options:

OptionDescription
ValueSet the value for each threshold.
Thresholds modeChoose from Absolute and Percentage.

To learn more, refer to Configure thresholds.

Value mappings

Value mapping is a technique you can use to change how data appears in a visualization.

For each value mapping, set the following options:

  • Condition - Choose what’s mapped to the display text and (optionally) color:
    • Value - Specific values
    • Range - Numerical ranges
    • Regex - Regular expressions
    • Special - Special values like Null, NaN (not a number), or boolean values like true and false
  • Display text
  • Color (Optional)
  • Icon (Canvas only)

To learn more, refer to Configure value mappings.

Field overrides

Overrides allow you to customize visualization settings for specific fields or series. When you add an override rule, it targets a particular set of fields and lets you define multiple options for how that field is displayed.

Choose from the following override options:

OptionDescription
Fields with nameSelect a field from the list of all available fields.
Field with name matching regexSpecify fields to override with a regular expression.
Fields with typeSelect fields by type, such as string, numeric, or time.
Fields returned by querySelect all fields returned by a specific query, such as A, B, or C.
Fields with valuesSelect all fields returned by your defined reducer condition, such as Min, Max, Count, Total.

To learn more, refer to Configure field overrides.