Skip to content

Nested Layouts Example

A board demonstrating complex layouts using nested sections.

Complete Board

title: "Dashboard with Nested Layouts"

source: db

queries:
  totals:
    sql: |
      SELECT SUM(revenue) AS total_revenue, SUM(documents_created) AS documents
      FROM dundersign_serving.monthly_metrics

  monthly:
    sql: |
      SELECT month, revenue, active_users, documents_created
      FROM dundersign_serving.monthly_metrics
      WHERE month > (SELECT MIN(month) FROM dundersign_serving.monthly_metrics)
        AND month < (SELECT MAX(month) FROM dundersign_serving.monthly_metrics)
      ORDER BY month

rows:
  # Level 1: Main Container
  - cols:
      # Left sidebar (auto width if not specified)
      - width: "25%"
        rows:
          - title: "KPIs"
            charts:
              revenue_kpi:
                label: "Revenue"
                query: queries.totals
                type: kpi
                value: total_revenue
              documents_kpi:
                label: "Documents"
                query: queries.totals
                type: kpi
                value: documents

            # Sidebar content - stacked KPIs
            rows:
              - revenue_kpi
              - documents_kpi

      # Main content (75% width)
      - width: "75%"
        rows:
          - title: "Trends"
            # Top charts row
            cols:
              - revenue_trend:
                  title: "Revenue"
                  query: queries.monthly
                  type: line
                  x: month
                  y: revenue
              - users_trend:
                  title: "Active Users"
                  query: queries.monthly
                  type: line
                  x: month
                  y: active_users

          # Bottom chart (full width)
          - details_table:
              title: "Monthly Details"
              query: queries.monthly
              type: table
Dashboard with Nested Layouts KPIs 25k Revenue 62k Documents Trends Oct2025NovDecJan2026FebMarAprMayJunJul01,0002,0003,000RevenueOct2025NovDecJan2026FebMarAprMayJunJul05001,000Active Users Monthly DetailsMonthRevenueActive usersDocuments created1 Oct 20253482871,1401 Nov 20258166382,5271 Dec 20252,6941,1157,8101 Jan 20262,4961,1895,2361 Feb 20263,2919604,4771 Mar 20261,5069047,0441 Apr 20262,7278175,5111 May 20262,1488555,9561 Jun 20263,0068747,5051 Jul 20262,3558137,245 Data as of 14:30 UTC on 20 Oct 2026 made withdbt Charts
▶

Layout Explanation

Visual Structure

┌─────────────┬──────────────────────────────────┐
│   KPIs      │         Trends                   │
│             │                                  │
│ Revenue KPI │ ┌────────────┬────────────┐      │
│             │ │ Revenue    │ Active     │      │
│ Docs KPI    │ │ Trend      │ Users      │      │
│             │ └────────────┴────────────┘      │
│             │                                  │
│             │ ┌─────────────────────────┐      │
│             │ │ Monthly Details Table   │      │
│             │ └─────────────────────────┘      │
└─────────────┴──────────────────────────────────┘

Nesting Levels

  1. Root Board: Has a rows layout (default).
  2. Row 1: Has a cols layout to split Sidebar (25%) vs Main (75%).
  3. Sidebar: Has a rows layout to stack KPIs vertically.
  4. Main: Has a rows layout to stack Trends on top of Details.
  5. Trends: Has a cols layout to put the Revenue and Active Users charts side-by-side.

Key Concepts

Alternating Row/Column Splits

The pattern for nested layouts: - Rows: Stack vertical - Cols: Stack horizontal - Grid: 2D arrangement

This creates flexible, responsive layouts.

Board Nesting

Any item in a layout list can be another full board definition:

rows:
  - cols:  # Nested board
      - item_1
      - item_2

Layout Types in Nested Sections

Each nested board can have its own layout: - rows: Vertical arrangement - cols: Horizontal arrangement - grid: Grid layout - tabs: Tabbed organization

When to Use Nested Layouts

Sidebar + Main Content

Use cols for the main split:

cols:
  - width: "250px"
    rows: [...] # Sidebar content
  - rows: [...] # Main content

Multi-Column Layouts

Create multi-column boards:

cols:
  - rows: [...] # Column 1
  - rows: [...] # Column 2
  - rows: [...] # Column 3

Complex Grids

Combine nested sections with grid layouts:

rows:
  - grid:
      columns: 24
      items:
        - item: chart1
          width: 12
        - item: chart2
          width: 12

Best Practices

Limit Nesting Depth

Avoid too many nesting levels (3-4 max): - Harder to understand - More complex to maintain - Can impact performance

Use Descriptive Titles

Add titles to nested sections for clarity:

rows:
  - title: "KPIs"
    cols: [...]

Narrow Screens

A board is a fixed-width frame that the page scales; nested layouts never reflow or stack. cols keeps every item side by side, so a row with many items gives each one little width. For a narrow target, set style.frame.width and size the rows for it (see Sizing).