Skip to content

Boards

Boards are the fundamental building blocks of dbt Charts. They are containers that define what to render (charts, text), how to render it (layout type), and where to place it. Since boards can contain other boards, you can nest them infinitely to create complex, structured layouts.

Basic Board Structure

A board defines layout and content. The layout is determined by the presence of type-specific keys (for example, rows, cols, grid, tabs).

# A simple board with rows (vertical stack)
source: examples_db
title: "Sales Overview"

queries:
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
  sales_by_date:
    sql: |
      SELECT date, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date ORDER BY date

charts:
  revenue:
    query: sales_by_category
    type: bar
    x: category
    y: revenue
  orders:
    query: sales_by_date
    type: line
    x: date
    y: units_sold
  trend:
    query: sales_by_date
    type: line
    x: date
    y: revenue

rows:
  - title: "KPIs"
    cols: # Horizontal stack
      - revenue
      - orders

  - title: "Trends"
    rows: # Nested vertical stack
      - trend
Sales Overview KPIs 01mn2mn3mn4mnElectronicsAccessoriesToolsJan2024FebMarAprMayJun1,0001,5002,0002,500 Trends 1Jan'2481522295Feb1219264Mar1118251Apr81522296May1320273Jun1017240   ​20   ​40   ​60   ​80K Data as of 14:30 UTC on 20 Oct 2026 made withdbt Charts
▶

Core Concepts

Layout Types

Boards support four layout types that determine how children are arranged:

Layout Key Description
Rows rows: Vertical stack (default)
Cols cols: Horizontal side-by-side
Grid grid: Flexible grid with positioning
Tabs tabs: Tabbed interface

See Layouts for detailed examples of each type.

Recursive Structure

Boards can contain charts OR other boards. This recursive structure means you can nest and vary layouts infinitely to create complex designs.

title: "Company Dashboard"
rows:
  - title: "Sales"
    cols:
      - title: "Q1"
        rows: ...
      - title: "Q2"
        rows: ...

  - title: "Marketing"
    rows: ...

Field Reference

# Board fields
title: string              # Optional display title
notes: string                # Optional AI search metadata; never appears in the rendered board (Cloud shows it in the dashboard-card hover)

# Layout (choose one)
rows: [items]              # Vertical stack
cols: [items]              # Horizontal stack
grid:                      # Grid layout
  columns: number
  items: [grid_items]
tabs:                      # Tabbed interface
  items: [tab_items]

# Content
text: string            # Markdown content block
charts:                    # Chart definitions
  <chart_id>: {...}
queries:                   # Query definitions
  <query_id>: {...}
variables:                 # Variable definitions
  <var_id>: {...}

# Styling
style:
  background: string       # Background color (hex, rgb, or named color)
  border: string           # CSS border shorthand (for example, "3px solid #667eea")
  # border:                # Or nested block for radius + color + width separately
  #   radius: number       #   Border radius in px (for example, 12)
  #   color: string        #   Border color
  #   width: number        #   Border width in px
  font:
    color: string          # Text color (hex, rgb, or named color)

Board Styling

Boards support styling properties that control their visual appearance. Styles are applied to nested boards to create visual hierarchy and organization.

Style Properties

rows:
  - title: "Styled Section"
    style:
      background: "#f5f5f5"        # Background color
      border:
        color: "#667eea"           # Border color
        width: 2                   # Border width (px)
        radius: 12                 # Rounded corners (px)
      font:
        color: "#667eea"           # Text color
    cols:
      - chart1
      - chart2

Available Style Properties

Property Type Description Example
background string Background color (hex, rgb, or named color) "#f5f5f5", "rgb(255, 0, 0)", "white"
border string or mapping CSS border shorthand, or nested block with color, width, radius "2px solid #667eea" or {color: "#667eea", width: 2, radius: 12}
font.color string Text color for prose and titles (to color titles alone, use style.title.font.color) "#667eea", "#333", "red"

Styling Examples

Colored Border with Rounded Corners: 

rows:
  - title: "Main Container"
    style:
      border:
        color: "#667eea"
        width: 3
        radius: 12
      font:
        color: "#667eea"
    cols:
      - text: "This section has a colored border and rounded corners."

Background with Border: 

rows:
  - title: "Highlighted Section"
    style:
      background: "#fff3cd"
      border:
        color: "#ffc107"
        width: 1
        radius: 8
    rows:
      - chart1
      - chart2

Nested Styling: 

rows:
  - title: "Outer Container"
    style:
      border:
        color: "#764ba2"
        width: 2
        radius: 8
    cols:
      - title: "Inner Section"
        style:
          border:
            color: "#9c27b0"
            width: 1
            radius: 6
          font:
            color: "#9c27b0"
        text: "Nested boards can have their own styles."

Style Inheritance

A child board inherits its parent's style, including frame, layout and gap, whether or not it sets its own style:. padding, margin, footer, timestamp and background are per board and never inherited.

Focusing a Single Chart

To get one chart on its own, append a single line to the bottom of any board:

chart_focus: <chart_id>

That renders just that chart in its own minimal layout, dropping every other chart and any variable it doesn't depend on; useful for embedding a single chart on another page, or exporting it standalone (SVG/PNG) without exporting the whole board around it. Nothing above it has to change:

title: "Sales Overview"

source: examples_db
queries:
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC

charts:
  revenue:
    query: sales_by_category
    type: bar
    x: category
    y: revenue
  orders:
    query: sales_by_category
    type: kpi
    value: revenue

rows:
  - revenue
  - orders

# Append this one line and only the revenue chart renders:
# no other part of the board changes. Delete it to get the board back.
chart_focus: revenue
01mn2mn3mn4mnElectronicsAccessoriesTools Data as of 14:30 UTC on 20 Oct 2026 made withdbt Charts
▶

Only revenue renders. orders is dropped, and so is the board's own title:; a focused view has no board-level title. The focused chart renders at its own width, as if it were the only chart on a board with no width: its authored width:, else its preferred width (a table hugs its columns). It does not keep the slot it had on the dashboard, and an authored board frame.width does not carry over.

chart_focus is a root-level key, so it takes effect wherever you put it in the root board's file; the bottom just keeps it to one appended line. Setting it on a nested board is a no-op.

Metadata Fields

A few root-level fields describe a board without changing how it renders:

Field Description
tags List of strings for categorizing boards. dct search filters by tag (a board matches only when it has all requested tags). 
title: "Weekly Revenue"
tags: [sales, weekly, revenue]
  • Layouts - Rows, cols, grid, and tabs
  • Content - Markdown and mixed content
  • Sizing - Width and height control
  • Imports - Reusability and file imports
  • Examples - Advanced layout patterns
  • Charts - Chart configuration
  • Themes - The built-in themes and how to write your own
  • Styling - Colors, fonts, borders, and formats