Skip to content

Layout Types Reference

Detailed reference for all layout types available in dbt Charts boards.

Note: This page provides detailed reference material. For conceptual overview and common patterns, see the Boards Guide.

Layout Types Overview

dbt Charts supports four primary layout types for organizing content:

  • Rows (rows): Vertical stack (default for top-level boards)
  • Cols (cols): Horizontal stack
  • Grid (grid): Two-dimensional positioning
  • Tabs (tabs): Tabbed content organization

Any item within these layouts can be a Chart, Content Block, or a Nested Board, allowing for infinite recursion.

A rows/cols section or a grid item can also be made collapsible with the Details modifier.

Rows Layout

Description

Arranges items sequentially, one after another (vertically). This is the standard "document flow" layout.

Configuration

rows:
  - item_1
  - item_2
  - item_3

Behavior

  • Items stack vertically.
  • Each item takes the full width of the container (unless restricted by a parent).
  • Height is determined by the item's content or explicit height property.

Example

title: "Monthly Report"
rows:
  - title: "KPIs"
    cols: [...]  # Nested horizontal layout

  - title: "Revenue Trend"
    type: line
    query: queries.revenue

  - title: "Detailed Table"
    type: table
    query: queries.details

Cols Layout

Description

Arranges items side-by-side (horizontally).

Configuration

cols:
  - item_1
  - item_2

Behavior

  • Items are placed horizontally.
  • Width is divided equally among items by default (for example, 3 items = 33% each).
  • You can override widths using the width property on individual items.
  • cols never stacks: the board is a fixed-width frame that the page scales, so every item keeps its share of the width. See Sizing.

Item Options

Field Type Description
width string/number Explicit width: "50%", "300px", or a bare number meaning pixels (not a relative weight)

Example

# 50/50 Split
cols:
  - title: "Revenue"
    type: bar
    query: queries.revenue

  - title: "Orders"
    type: line
    query: queries.orders

# 70/30 Split
cols:
  - width: "70%"
    title: "Main Chart"
    # ...
  - width: "30%"
    title: "Sidebar"
    # ...

Grid Layout

Description

Arranges items in a precise 2D grid. Items can flow naturally into the next available space or be pinned to specific coordinates.

Configuration

grid:
  columns: 24           # Number of vertical columns
  items:
    - item: item_1
    - item: item_2

Grid Options

Field Type Description
columns number Number of vertical columns (default: 24)
items list The items to place in the grid

Grid rows size to their content, and every item spans one column and one row unless it says otherwise. Spacing between cells is set by style.layout.grid.gap, in pixels.

Item Options

Grid items support specific positioning properties:

Field Type Description
col number Starting column index (0-based)
row number Starting row index (0-based)
col_span number Number of columns to span (default: 1)
row_span number Number of rows to span (default: 1)

Clear naming

We use col_span and row_span instead of width and height to avoid confusion with pixel dimensions.

Behavior

  • Auto-Flow: Items without col and row are placed automatically in the next available space.
  • Pinned: Items with col and row are fixed to that position.
  • Overlap: Pinned items can overlap other items.

Example

grid:
  columns: 24
  items:
    # Top Row: 3 KPIs (8 columns each)
    - col_span: 8
      item: kpi_1
    - col_span: 8
      item: kpi_2
    - col_span: 8
      item: kpi_3

    # Middle: Main Chart (16 cols) + List (8 cols)
    - col_span: 16
      row_span: 4
      item: main_chart
    - col_span: 8
      row_span: 4
      item: recent_activity_list

Tabs Layout

Description

Organizes content into switchable tabs. Useful for grouping related but distinct views without cluttering the screen.

Configuration

tabs:
  position: top       # Tab bar position (top, left)
  items:
    - title: "Tab 1"
      rows: [...]     # Content for Tab 1
    - title: "Tab 2"
      cols: [...]     # Content for Tab 2

Tab Item Options

Field Type Description
title string Required: Label text
icon string Optional icon name

Tab content is placed via direct rows:, cols:, grid:, or tabs: keys on the tab item itself; there is no separate layout: field.

Example

tabs:
  items:
    - title: "Overview"
      rows:
        - kpi_row
        - trend_chart

    - title: "Regional"
      cols:
        - map_view
        - regional_table

Details (Collapsible Sections)

Description

A rows/cols section or a grid item's item: board can be made collapsible by adding a details property. This renders a clickable summary bar with a disclosure triangle (▶/▼) that expands or collapses the content. Works like HTML <details>/<summary>.

The expanded/collapsed state is controlled by an auto-generated hidden variable and toggled via URL parameters; no JavaScript required.

Configuration

Add details to a section within a layout. Tab items, grid item wrappers and bare chart references reject it:

rows:
  - details:
      summary: "Show More"      # Summary text (clickable header)
      expanded_title: "Hide"    # Optional: different text when expanded
      expanded: false          # Optional: default state (default: false)
    id: breakdown               # Optional: URL param name (auto-generated if omitted)
    rows:                       # Content (any layout type)
      - text: Breakdown
      - text: Detail

Item Options

Field Type Default Description
details.summary string (required) Summary text shown in the clickable header
details.expanded_title string same as details.summary Different text shown when expanded
details.expanded boolean false Whether the section starts expanded
id string auto-generated URL parameter name for the toggle variable

Behavior

  • Collapsed: Only the summary bar is rendered (36px). Content is not rendered at all.
  • Expanded: Summary bar + full content below it.
  • Toggle: Clicking the summary bar navigates to a URL that flips the variable, triggering a server re-render.
  • URL state: The toggle variable appears in the URL as ?breakdown=true or ?breakdown=false, preserving all other parameters.
  • Sizing: Height adjusts automatically; collapsed sections take minimal space.

Example

title: "Sales Dashboard"
rows:
  - text: Summary

  - details:
      summary: "Revenue Breakdown"
      expanded_title: "Hide Breakdown"
    rows:
      - text: By region
      - text: By product

  - details:
      summary: "Raw Data"
      expanded: true
    id: raw_data
    rows:
      - text: Raw data

This renders: 

┌──────────────────────────────────┐
│  [summary_kpis]                  │
├──────────────────────────────────┤
│ ▶ Revenue Breakdown              │  ← click to expand
├──────────────────────────────────┤
│ ▼ Raw Data                       │  ← starts expanded
│  [raw_data_table]                │
└──────────────────────────────────┘

Comparison Table

Layout Type Best For Responsive Behavior Complexity
Rows Standard reports, mobile-first Stacks vertically (naturally) Low
Cols Side-by-side comparisons, sidebars Fixed frame; never stacks Low
Grid Dense dashboards, precise control Reflows or scales based on config High
Tabs Reducing clutter, categorization Tab bar adapts (scrolls or menu) Medium
Details Collapsible sections, progressive disclosure Collapses to single row Low

Best Practices

  1. Start with Rows: Most dashboards are effectively a stack of sections. Start with a rows layout and nest other layouts inside.
  2. Use Cols for comparisons: Place related metrics side-by-side for easy comparison.
  3. Limit Nesting: While dbt Charts supports infinite nesting, sticking to 2-3 levels usually produces the most maintainable and readable boards.
  4. Narrow targets: cols never stacks, so five charts across a 700px frame get about 115px each, too narrow for a bar chart's axis labels. For a narrow target, set style.frame.width and size the rows for it (see Sizing).