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 (e.g., 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

▶

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
description: string        # Optional help text

# 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 (e.g., "3px solid #667eea")
  # border:                # Or nested block for radius + color + width separately
  #   radius: number       #   Border radius in px (e.g., 12)
  #   color: string        #   Border color
  #   width: number        #   Border width in px
  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)
      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}`
`color`	string	Text color (affects titles and content)	`"#667eea"`, `"#333"`, `"red"`

Styling Examples¶

Colored Border with Rounded Corners:

rows:
  - title: "Main Container"
    style:
      border:
        color: "#667eea"
        width: 3
        radius: 12
      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
          color: "#9c27b0"
        text: "Nested boards can have their own styles."

Style Inheritance¶

Styles are not inherited by child boards. Each board defines its own styling independently. This allows for precise control over the visual appearance of each section.

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

▶

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 keeps the width its layout slot had on the dashboard, so it looks exactly like the chart you focused, just on its own.

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
Styling - Themes and colors