Skip to content

Nested Layouts Example

A board demonstrating complex layouts using nested sections.

Complete Board

title: "Board with Nested Layouts"

queries:
  totals:
    metrics: [total_revenue, order_count]

  sales:
    metrics: [total_revenue, order_count]
    dimensions: [month, region]

rows:
  # Level 1: Main Container
  - cols:
      # Left sidebar (auto width if not specified)
      - width: "25%"
        rows:
          - title: "KPIs"
            charts:
              revenue_kpi:
                title: "Revenue"
                query: queries.totals
                type: kpi
                metric: total_revenue
              orders_kpi:
                title: "Orders"
                query: queries.totals
                type: kpi
                metric: order_count

            # Sidebar content - stacked KPIs
            cols:
              - revenue_kpi
              - orders_kpi

      # Main content (75% width)
      - width: "75%"
        rows:
          - title: "Trends"
            # Top charts row
            cols:
              - revenue_trend:
                  query: queries.sales
                  type: line
                  x: month
                  y: total_revenue
              - orders_trend:
                  query: queries.sales
                  type: line
                  x: month
                  y: order_count

          # Bottom chart (full width)
          - details_table:
              title: "Sales Details"
              query: queries.sales
              type: table

Layout Explanation

Visual Structure

┌─────────────┬──────────────────────────────────┐
│   KPIs      │         Trends                   │
│             │                                  │
│ Revenue KPI │ ┌────────────┬────────────┐      │
│             │ │ Revenue    │ Orders     │      │
│ Orders KPI  │ │ Trend      │ Trend      │      │
│             │ └────────────┴────────────┘      │
│             │                                  │
│             │ ┌─────────────────────────┐      │
│             │ │ Sales 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 Revenue and Orders 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: 12
      items:
        - item: chart1
          width: 6
        - item: chart2
          width: 6

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