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

▶

Layout Explanation¶

Visual Structure¶

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

Nesting Levels¶

Root Board: Has a rows layout (default).
Row 1: Has a cols layout to split Sidebar (25%) vs Main (75%).
Sidebar: Has a rows layout to stack KPIs vertically.
Main: Has a rows layout to stack Trends on top of Details.
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: [...]

Test Responsive Behavior¶

Nested layouts adapt to screen size: - cols layouts wrap to vertical stacks on mobile - grid layouts reflow based on available width

Boards Guide - Learn about boards and layouts
Layout Types Reference - Detailed layout reference