--- title: "layout | Grafana documentation" description: "A reference for the JSON layout schema used with Observability as Code." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # `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](#gridlayoutkind) - Corresponds to the **Custom** option in the UI. You define panel size and panel positions using x- and y- settings. - [AutoGridLayoutKind](#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](#rowslayoutkind) - Groups panels into rows. - [TabsLayoutKind](#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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json "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](#gridlayoutitemspec) - GridLayoutRowKind - kind: “GridLayoutRow” - spec: [GridLayoutRowSpec](#gridlayoutrowspec) ### `GridLayoutItemSpec` The following table explains the usage of the grid layout item JSON fields: Expand table | 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`](/docs/grafana/v12.4/observability-as-code/schema-v2/panel-schema/) from `dashboard.spec.elements` expressed as JSON Schema reference. | | repeat? | [RepeatOptions](#repeatoptions). Configured repeat options, if any | #### `RepeatOptions` The following table explains the usage of the repeat option JSON fields: Expand table | 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: Expand table | Name | Usage | |-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | y | integer. Position of the row y-axis | | collapsed | bool. Whether or not the row is collapsed | | title | Row title | | elements | [`[...GridLayoutItemKind]`](#gridlayoutitemspec). 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](#rowrepeatoptions) Configured row repeat options, if any | #### `RowRepeatOptions` Expand table | 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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json "kind": "AutoGridLayout", "spec": { "columnWidthMode": "standard", "fillScreen": false, "items": [ { "kind": "AutoGridLayoutItem", "spec": { "element": {...}, } } ], "maxColumnCount": 3, "rowHeightMode": "standard" } ``` `AutoGridLayoutKind` consists of: - kind: “AutoGridLayout” - spec: [AutoGridLayoutSpec](#autogridlayoutspec) ### `AutoGridLayoutSpec` The following table explains the usage of the auto grid layout JSON fields: Expand table NameUsage maxColumnCount?number. Default is `3`. columnWidthModeOptions are: `narrow`, `standard`, `wide`, and `custom`. Default is `standard`. columnWidth?number rowHeightModeOptions 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) #### `AutoGridLayoutItemSpec` The following table explains the usage of the auto grid layout item JSON fields: Expand table NameUsage element`ElementReference`. Reference to a [`PanelKind`](/docs/grafana/v12.4/observability-as-code/schema-v2/panel-schema/) from `dashboard.spec.elements` expressed as JSON Schema reference. repeat?[AutoGridRepeatOptions](#autogridrepeatoptions). Configured repeat options, if any. conditionalRendering?`ConditionalRenderingGroupKind`. Rules for hiding or showing panels, if any. Consists of: - kind: “ConditionalRenderingGroup” - spec: [ConditionalRenderingGroupSpec](#conditionalrenderinggroupspec) ##### `AutoGridRepeatOptions` The following table explains the usage of the auto grid repeat option JSON fields: Expand table | Name | Usage | |-------|---------------------------| | mode | `RepeatMode` - “variable” | | value | String | ##### `ConditionalRenderingGroupSpec` Expand table NameUsage visibilityOptions are `show` and `hide` conditionOptions are `and` and `or` itemsOptions are: - ConditionalRenderingVariableKind - kind: “ConditionalRenderingVariable” - spec: [ConditionalRenderingVariableSpec](#conditionalrenderingvariablespec) - ConditionalRenderingDataKind - kind: “ConditionalRenderingData” - spec: [ConditionalRenderingDataSpec](#conditionalrenderingdataspec) - ConditionalRenderingTimeRangeSizeKind - kind: “ConditionalRenderingTimeRangeSize” - spec: [ConditionalRenderingTimeRangeSizeSpec](#conditionalrenderingtimerangesizespec) ###### `ConditionalRenderingVariableSpec` Expand table | Name | Usage | |----------|--------------------------------------| | variable | string | | operator | Options are `equals` and `notEquals` | | value | string | ###### `ConditionalRenderingDataSpec` Expand table | Name | Type | |-------|------| | value | bool | ###### `ConditionalRenderingTimeRangeSizeSpec` Expand table | 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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json "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) ### `RowsLayoutRowSpec` The following table explains the usage of the rows layout row JSON fields: Expand table NameUsage title?Title of the row. collapsebool. 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](#conditionalrenderinggroupspec) repeat?[RowRepeatOptions](#rowrepeatoptions). Configured repeat options, if any. layoutSupported layouts are: - [GridLayoutKind](#gridlayoutkind) - [RowsLayoutKind](#rowslayoutkind) - [AutoGridLayoutKind](#autogridlayoutkind) - [TabsLayoutKind](#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: JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json "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) ### `TabsLayoutTabSpec` The following table explains the usage of the tabs layout tab JSON fields: Expand table NameUsage title?The title of the tab. layoutSupported layouts are: - [GridLayoutKind](#gridlayoutkind) - [RowsLayoutKind](#rowslayoutkind) - [AutoGridLayoutKind](#autogridlayoutkind) - [TabsLayoutKind](#tabslayoutkind) conditionalRendering?`ConditionalRenderingGroupKind`. Rules for hiding or showing panels, if any. Consists of: - kind: “ConditionalRenderingGroup” - spec: [ConditionalRenderingGroupSpec](#conditionalrenderinggroupspec)