Skip to content

Board Layouts

The layout of a board determines how its children (charts and nested boards) are arranged. dbt Charts supports four layout types.

Rows (Vertical Stack)

Items are arranged vertically, one after another. This is the default structure for top-level boards.

source: examples_db
title: "Sales Dashboard"

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
  sales_by_product:
    sql: |
      SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC

charts:
  revenue_by_category:
    query: sales_by_category
    type: bar
    title: "Revenue by Category"
    x: category
    y: revenue
  orders_trend:
    query: sales_by_date
    type: line
    title: "Orders Over Time"
    x: date
    y: units_sold
  products_breakdown:
    query: sales_by_product
    type: pie
    title: "Product Breakdown"
    theta: revenue
    color: product

rows:
  - revenue_by_category
  - orders_trend
  - products_breakdown
Sales Dashboard 01mn2mn3mn4mnElectronicsAccessoriesToolsRevenue by CategoryJan2024FebMarAprMayJun1,0001,5002,0002,500Orders Over TimeProduct Breakdown20% Widget B1,753,13618% Widget A1,556,94014% Gadget Y1,245,30014% Gadget X1,189,52411% Tool Z990,9449% Widget C788,200 Data as of 14:30 UTC on 20 Oct 2026 made withdbt Charts
▶

Use rows when: - Content should flow vertically - Building mobile-friendly layouts - Creating scrollable dashboards

Cols (Horizontal Stack)

Items are arranged horizontally, side-by-side.

source: examples_db
title: "Comparison View"

queries:
  sales_by_product:
    sql: |
      SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, 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
  sales_summary:
    sql: |
      SELECT SUM(revenue) AS revenue, SUM(units_sold) AS units_sold, COUNT(DISTINCT category) AS category_count FROM ecommerce_orders

charts:
  revenue:
    query: sales_by_product
    type: bar
    title: "Revenue"
    x: product
    y: revenue
  orders:
    query: sales_by_date
    type: line
    title: "Orders"
    x: date
    y: units_sold
  growth:
    query: sales_summary
    type: kpi
    label: "Total Revenue"
    value: revenue

cols:
  - revenue
  - orders
  - growth
Comparison View 0500k1,000k1,500kWidget BWidget AGadget YGadget XTool ZWidget CTool AGadget ZRevenueJan2024FebMarAprMayJun1,0001,5002,0002,500Orders8.7mn Total Revenue Data as of 14:30 UTC on 20 Oct 2026 made withdbt Charts
▶

Use cols when: - Comparing metrics side-by-side - Creating sidebars - Building wide-screen layouts

Grid Layout

Items are arranged in a flexible grid. Items flow automatically into the next available space, but you can control their position and size using col, row, width and height.

source: examples_db
title: "Grid Dashboard"

queries:
  sales_summary:
    sql: |
      SELECT SUM(revenue) AS revenue, SUM(units_sold) AS units_sold, COUNT(DISTINCT category) AS category_count FROM ecommerce_orders
  sales_by_product:
    sql: |
      SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
  sales:
    sql: |
      SELECT * FROM ecommerce_orders

charts:
  kpi1:
    query: sales_summary
    type: kpi
    label: "Total Revenue"
    value: revenue
  kpi2:
    query: sales_summary
    type: kpi
    label: "Units Sold"
    value: units_sold
  kpi3:
    query: sales_summary
    type: kpi
    label: "Categories"
    value: category_count
  main_chart:
    query: sales_by_product
    type: bar
    title: "Revenue by Product"
    x: product
    y: revenue
  sales_table:
    query: sales
    type: table
    title: "Sales Data"

grid:
  columns: 24
  items:
    - item: kpi1
      width: 8
    - item: kpi2
      width: 8
    - item: kpi3
      width: 8
    - item: main_chart
      width: 24
    - item: sales_table
      width: 24
Grid Dashboard 8.7mn Total Revenue 290k Units Sold 3 Categories 0500k1,000k1,500kWidget BWidget AGadget YGadget XTool ZWidget CTool AGadget ZRevenue by ProductSales DataDateRegionProductCategoryRevenueUnits sold21 Feb 2024NorthWidget CElectronics2,150868 Mar 2024NorthTool ATools5951726 Apr 2024EastGadget XAccessories1,5984717 Jun 2024NorthWidget AElectronics1,5905319 Apr 2024EastWidget BElectronics8122921 Mar 2024WestGadget ZAccessories1,5405516 Jun 2024NorthWidget AElectronics1,5905318 Jun 2024WestWidget BElectronics2,2408014 Jun 2024WestGadget XAccessories1,394413 May 2024WestTool ZTools5121623 Feb 2024SouthGadget YAccessories1,3204426 Mar 2024SouthTool ZTools480151 Apr 2024SouthWidget BElectronics980357 May 2024WestWidget BElectronics2,324838 May 2024NorthWidget BElectronics1,148414 Mar 2024SouthGadget ZAccessories924334 Feb 2024NorthGadget YAccessories450154 Apr 2024WestGadget XAccessories5101521 Jun 2024EastWidget AElectronics600204 May 2024EastWidget AElectronics1,290431–20 / 6270‹12…314› Data as of 14:30 UTC on 20 Oct 2026 made withdbt Charts
▶

Grid Features

  • Flow: Items without col,row fill the next available space
  • Pinning: Items with col,row are fixed to that position
  • Default span: An item that sets neither width nor height spans one column and one row
  • Overlapping: Multiple items can occupy the same cells
  • Row height: Grid rows size to their content: set a per-item height in row units to make an item taller
  • Gap: Spacing between cells is set by style.layout.grid.gap, in pixels

Note: Sizing properties (width, height, col, row) are defined on the layout item, not the chart itself.

Tab Layout

Organize items into tabs. Each item in the items list is a nested board that defines the content for that tab.

source: examples_db
title: "Multi-Tab Dashboard"

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
  sales:
    sql: |
      SELECT * FROM ecommerce_orders

charts:
  summary:
    query: sales_by_category
    type: bar
    title: "Summary Chart"
    x: category
    y: revenue
  revenue_trend:
    query: sales_by_date
    type: line
    title: "Revenue Trend"
    x: date
    y: revenue
  orders_trend:
    query: sales_by_date
    type: line
    title: "Orders Trend"
    x: date
    y: units_sold
  details:
    query: sales
    type: table
    title: "Detailed Table"

tabs:
  items:
    - title: "Overview"
      rows:
        - summary

    - title: "Trends"
      cols:
        - revenue_trend
        - orders_trend

    - title: "Details"
      rows:
        - details
Multi-Tab Dashboard Overview Trends Details Overview 01mn2mn3mn4mnElectronicsAccessoriesToolsSummary Chart Data as of 14:30 UTC on 20 Oct 2026 made withdbt Charts
▶

Use tabs when: - Managing dashboard density - Organizing related views - Hiding content until needed

Details (Collapsible Sections)

A rows/cols section or a grid item's item: board can be made collapsible by adding details. This renders a clickable summary bar that expands/collapses the content; no JavaScript needed.

A tab item rejects details, as do inline chart items and the grid item wrapper; to collapse content inside a tab, put a details section in the tab's rows:.

tabs:
  items:
    - title: Overview
      details:
        summary: Show more
      rows:
        - text: Content

source: examples_db
title: "Dashboard with Details"

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:
    sql: |
      SELECT * FROM ecommerce_orders

charts:
  summary:
    query: sales_by_category
    type: bar
    title: "Revenue Summary"
    x: category
    y: revenue
  breakdown:
    query: sales
    type: table
    title: "Full Data"

rows:
  - summary

  - details:
      summary: "Show Raw Data"
      expanded_title: "Hide Raw Data"
    rows:
      - breakdown
Dashboard with Details 01mn2mn3mn4mnElectronicsAccessoriesToolsRevenue Summary▶Show Raw Data Data as of 14:30 UTC on 20 Oct 2026 made withdbt Charts
▶

Use details when: - Hiding secondary content behind a toggle - Reducing dashboard clutter - Progressive disclosure of complex data

Choosing a Layout

Layout Best For
Rows Simple vertical flow, mobile, scrolling
Cols Comparing metrics, sidebars
Grid Precise control, dense dashboards
Tabs Multiple views, reducing clutter
Details Collapsible sections, progressive disclosure