Documentation

Grafana documentation

Observability as Code

JSON schema v2

layout schema

Grafana Cloud Enterprise Open source

`layout`

There are four layout options offering two types of panel control:

Panel layout options

These options control the size and position of panels:

GridLayoutKind - Corresponds to the Custom option in the UI. You define panel size and panel positions using x- and y- settings.
AutoGridLayoutKind - Corresponds to the Auto grid option in the UI. Panel size and position are automatically set based on column and row parameters.

Panel grouping options

These options control the grouping of panels:

RowsLayoutKind - Groups panels into rows.
TabsLayoutKind - Groups panels into tabs.

`GridLayoutKind`

The grid layout allows you to manually size and position grid items by setting the height, width, x, and y of each item. This layout corresponds to the Custom option in the UI.

Following is the JSON for a default grid layout, a grid layout item, and a grid layout row:

    "kind": "GridLayout",
    "spec": {
      "items": [
        {
          "kind": "GridLayoutItem",
          "spec": {
            "element": {...},
            "height": 0,
            "width": 0,
            "x": 0,
            "y": 0
          }
        },
        {
          "kind": "GridLayoutRow",
          "spec": {
            "collapsed": false,
            "elements": [],
            "title": "",
            "y": 0
          }
        },
      ]
    }

GridLayoutKind consists of:

kind: “GridLayout”
spec: GridLayoutSpec
- items: GridLayoutItemKind or GridLayoutRowKind
  - GridLayoutItemKind
    - kind: “GridLayoutItem”
    - spec: GridLayoutItemSpec
  - GridLayoutRowKind
    - kind: “GridLayoutRow”
    - spec: GridLayoutRowSpec

`GridLayoutItemSpec`

The following table explains the usage of the grid layout item JSON fields:

Name	Usage
x	integer. Position of the item x-axis.
y	integer. Position of the item y-axis.
width	Width of the item in pixels.
height	Height of the item in pixels.
element	`ElementReference`. Reference to a `PanelKind` from `dashboard.spec.elements` expressed as JSON Schema reference.
repeat?	RepeatOptions. Configured repeat options, if any

`RepeatOptions`

The following table explains the usage of the repeat option JSON fields:

Name	Usage
mode	`RepeatMode` - “variable”
value	string
direction?	Options are `h` for horizontal and `v` for vertical.
maxPerRow?	integer

`GridLayoutRowSpec`

The following table explains the usage of the grid layout row JSON fields:

Name	Usage
y	integer. Position of the row y-axis
collapsed	bool. Whether or not the row is collapsed
title	Row title
elements	`[...GridLayoutItemKind]`. Grid items in the row will have their y value be relative to the row’s y value. This means a panel positioned at `y: 0` in a row with `y: 10` will be positioned at `y: 11` (row header has a height of 1) in the dashboard.
repeat?	RowRepeatOptions Configured row repeat options, if any

`RowRepeatOptions`

Name	Usage
mode	`RepeatMode` - “variable”
value	string

`AutoGridLayoutKind`

With an auto grid, Grafana sizes and positions your panels for the best fit based on the column and row constraints that you set. This layout corresponds to the Auto grid option in the UI.

Following is the JSON for a default auto grid layout and a grid layout item:

    "kind": "AutoGridLayout",
    "spec": {
      "columnWidthMode": "standard",
      "fillScreen": false,
      "items": [
        {
          "kind": "AutoGridLayoutItem",
          "spec": {
            "element": {...},
          }
        }
      ],
      "maxColumnCount": 3,
      "rowHeightMode": "standard"
    }

AutoGridLayoutKind consists of:

kind: “AutoGridLayout”
spec: AutoGridLayoutSpec

`AutoGridLayoutSpec`

The following table explains the usage of the auto grid layout JSON fields:

Name	Usage
maxColumnCount?	number. Default is `3`.
columnWidthMode	Options are: `narrow`, `standard`, `wide`, and `custom`. Default is `standard`.
columnWidth?	number
rowHeightMode	Options are: `short`, `standard`, `tall`, and `custom`. Default is `standard`.
rowHeight?	number
fillScreen?	bool. Default is `false`.
items	`AutoGridLayoutItemKind`. Consists of: kind: “AutoGridLayoutItem” spec: AutoGridLayoutItemSpec

`AutoGridLayoutItemSpec`

The following table explains the usage of the auto grid layout item JSON fields:

Name	Usage
element	`ElementReference`. Reference to a `PanelKind` from `dashboard.spec.elements` expressed as JSON Schema reference.
repeat?	AutoGridRepeatOptions. Configured repeat options, if any.
conditionalRendering?	`ConditionalRenderingGroupKind`. Rules for hiding or showing panels, if any. Consists of: kind: “ConditionalRenderingGroup” spec: ConditionalRenderingGroupSpec

`AutoGridRepeatOptions`

The following table explains the usage of the auto grid repeat option JSON fields:

Name	Usage
mode	`RepeatMode` - “variable”
value	String

`ConditionalRenderingGroupSpec`

Name	Usage
visibility	Options are `show` and `hide`
condition	Options are `and` and `or`
items	Options are: ConditionalRenderingVariableKind kind: “ConditionalRenderingVariable” spec: ConditionalRenderingVariableSpec ConditionalRenderingDataKind kind: “ConditionalRenderingData” spec: ConditionalRenderingDataSpec ConditionalRenderingTimeRangeSizeKind kind: “ConditionalRenderingTimeRangeSize” spec: ConditionalRenderingTimeRangeSizeSpec

`ConditionalRenderingVariableSpec`

Name	Usage
variable	string
operator	Options are `equals` and `notEquals`
value	string

`ConditionalRenderingDataSpec`

Name	Type
value	bool

`ConditionalRenderingTimeRangeSizeSpec`

Name	Type
value	string

`RowsLayoutKind`

The RowsLayoutKind is one of two options that you can use to group panels. You can nest any other kind of layout inside a layout row. Rows can also be nested in auto grids or tabs.

Following is the JSON for a default rows layout row:

    "kind": "RowsLayout",
    "spec": {
      "rows": [
        {
          "kind": "RowsLayoutRow",
          "spec": {
            "layout": {
              "kind": "GridLayout", // Can also be AutoGridLayout or TabsLayout
              "spec": {...}
            },
            "title": ""
          }
        }
      ]
    }

RowsLayoutKind consists of:

kind: RowsLayout
spec: RowsLayoutSpec
- rows: RowsLayoutRowKind
  - kind: RowsLayoutRow
  - spec: RowsLayoutRowSpec

`RowsLayoutRowSpec`

The following table explains the usage of the rows layout row JSON fields:

Name	Usage
title?	Title of the row.
collapse	bool. Whether or not the row is collapsed.
hideHeader?	bool. Whether the row header is hidden or shown.
fullScreen?	bool. Whether or not the row takes up the full screen.
conditionalRendering?	`ConditionalRenderingGroupKind`. Rules for hiding or showing rows, if any. Consists of: kind: “ConditionalRenderingGroup” spec: ConditionalRenderingGroupSpec
repeat?	RowRepeatOptions. Configured repeat options, if any.
layout	Supported layouts are: GridLayoutKind RowsLayoutKind AutoGridLayoutKind TabsLayoutKind

`TabsLayoutKind`

The TabsLayoutKind is one of two options that you can use to group panels. You can nest any other kind of layout inside a tab. Tabs can also be nested in auto grids or rows.

Following is the JSON for a default tabs layout tab and a tab:

    "kind": "TabsLayout",
    "spec": {
      "tabs": [
        {
          "kind": "TabsLayoutTab",
          "spec": {
            "layout": {
              "kind": "GridLayout", // Can also be AutoGridLayout or RowsLayout
              "spec": {...}
            },
            "title": "New tab"
          }
        }
      ]
    }

TabsLayoutKind consists of:

kind: TabsLayout
- spec: TabsLayoutSpec
  - tabs: TabsLayoutTabKind
    - kind: TabsLayoutTab
    - spec: TabsLayoutTabSpec

`TabsLayoutTabSpec`

The following table explains the usage of the tabs layout tab JSON fields:

Name	Usage
title?	The title of the tab.
layout	Supported layouts are: GridLayoutKind RowsLayoutKind AutoGridLayoutKind TabsLayoutKind
conditionalRendering?	`ConditionalRenderingGroupKind`. Rules for hiding or showing panels, if any. Consists of: kind: “ConditionalRenderingGroup” spec: ConditionalRenderingGroupSpec