Skip to content

Layout Types Reference

Detailed reference for all layout types available in Dataface boards.

Note: This page provides detailed reference material. For conceptual overview and common patterns, see the Boards Guide.

Layout Types Overview

Dataface supports four primary layout types for organizing content:

  • Rows (rows): Vertical stack (default for top-level boards)
  • Cols (cols): Horizontal stack
  • Grid (grid): Two-dimensional positioning
  • Tabs (tabs): Tabbed content organization

Any item within these layouts can be a Chart, Content Block, Nested Board, or a foreach for dynamic generation, allowing for infinite recursion.

Any nested board item can also be made collapsible with the Details modifier.

Rows Layout

Description

Arranges items sequentially, one after another (vertically). This is the standard "document flow" layout.

Configuration

rows:
  - item_1
  - item_2
  - item_3

Behavior

  • Items stack vertically.
  • Each item takes the full width of the container (unless restricted by a parent).
  • Height is determined by the item's content or explicit height property.

Example

title: "Monthly Report"
rows:
  - title: "KPIs"
    cols: [...]  # Nested horizontal layout

  - title: "Revenue Trend"
    type: line
    query: queries.revenue

  - title: "Detailed Table"
    type: table
    query: queries.details

Cols Layout

Description

Arranges items side-by-side (horizontally).

Configuration

cols:
  - item_1
  - item_2

Behavior

  • Items are placed horizontally.
  • Width is divided equally among items by default (e.g., 3 items = 33% each).
  • You can override widths using the width property on individual items.
  • On mobile devices, cols layouts typically wrap to a vertical stack.

Item Options

Field Type Description
width string/number Explicit width (e.g., "50%", "300px", or integer relative weight)

Example

# 50/50 Split
cols:
  - title: "Revenue"
    type: bar
    query: queries.revenue

  - title: "Orders"
    type: line
    query: queries.orders

# 70/30 Split
cols:
  - width: "70%"
    title: "Main Chart"
    # ...
  - width: "30%"
    title: "Sidebar"
    # ...

Grid Layout

Description

Arranges items in a precise 2D grid. Items can flow naturally into the next available space or be pinned to specific coordinates.

Configuration

grid:
  columns: 12           # Number of vertical columns
  row_height: "100px"   # Base height for grid rows
  gap: "md"             # Spacing (sm, md, lg, xl)
  items:
    - item_1
    - item_2

Item Options

Grid items support specific positioning properties:

Field Type Description
col number Starting column index (0-based)
row number Starting row index (0-based)
col_span number Number of columns to span (default: 1)
row_span number Number of rows to span (default: 1)

Clear naming

We use col_span and row_span instead of width and height to avoid confusion with pixel dimensions.

Behavior

  • Auto-Flow: Items without col and row are placed automatically in the next available space.
  • Pinned: Items with col and row are fixed to that position.
  • Overlap: Pinned items can overlap other items.

Example

grid:
  columns: 12
  items:
    # Top Row: 3 KPIs (4 columns each)
    - col_span: 4
      item: kpi_1
    - col_span: 4
      item: kpi_2
    - col_span: 4
      item: kpi_3

    # Middle: Main Chart (8 cols) + List (4 cols)
    - col_span: 8
      row_span: 4
      item: main_chart
    - col_span: 4
      row_span: 4
      item: recent_activity_list

Tabs Layout

Description

Organizes content into switchable tabs. Useful for grouping related but distinct views without cluttering the screen.

Configuration

tabs:
  position: top       # Tab bar position (top, left)
  items:
    - title: "Tab 1"
      rows: [...]     # Content for Tab 1
    - title: "Tab 2"
      cols: [...]     # Content for Tab 2

Tab Item Options

Field Type Description
title string Required: Label text
icon string Optional icon name
layout * The content layout (rows, cols, grid)

Example

tabs:
  items:
    - title: "Overview"
      rows:
        - kpi_row
        - trend_chart

    - title: "Regional"
      cols:
        - map_view
        - regional_table

Details (Collapsible Sections)

Description

Any nested board item can be made collapsible by adding a details property. This renders a clickable summary bar with a disclosure triangle (▶/▼) that expands or collapses the content. Works like HTML <details>/<summary>.

The expanded/collapsed state is controlled by an auto-generated hidden variable and toggled via URL parameters — no JavaScript required.

Configuration

Add details to any nested board item within a layout:

rows:
  - details: "Show More"        # Summary text (clickable header)
    expanded_title: "Hide"      # Optional: different text when expanded
    expanded: false              # Optional: default state (default: false)
    id: breakdown               # Optional: URL param name (auto-generated if omitted)
    rows:                       # Content (any layout type)
      - chart: breakdown_chart
      - chart: detail_table

Item Options

Field Type Default Description
details string (required) Summary text shown in the clickable header
expanded_title string same as details Different text shown when expanded
expanded boolean false Whether the section starts expanded
id string auto-generated URL parameter name for the toggle variable

Behavior

  • Collapsed: Only the summary bar is rendered (36px). Content is not rendered at all.
  • Expanded: Summary bar + full content below it.
  • Toggle: Clicking the summary bar navigates to a URL that flips the variable, triggering a server re-render.
  • URL state: The toggle variable appears in the URL as ?breakdown=true or ?breakdown=false, preserving all other parameters.
  • Sizing: Height adjusts automatically — collapsed sections take minimal space.

Example

title: "Sales Dashboard"
rows:
  - chart: summary_kpis

  - details: "Revenue Breakdown"
    expanded_title: "Hide Breakdown"
    rows:
      - chart: revenue_by_region
      - chart: revenue_by_product

  - details: "Raw Data"
    expanded: true
    id: raw_data
    rows:
      - chart: data_table

This renders: 

┌──────────────────────────────────┐
│  [summary_kpis]                  │
├──────────────────────────────────┤
│ ▶ Revenue Breakdown              │  ← click to expand
├──────────────────────────────────┤
│ ▼ Raw Data                       │  ← starts expanded
│  [data_table]                    │
└──────────────────────────────────┘

Foreach Construct

Description

Dynamically generates layout items by iterating over inline data. Useful for auto-generating charts, data profiling, or creating repetitive sections programmatically.

Configuration

rows:  # (or cols)
  - foreach:
      query:
        data:
          - name: "Item A"
            value: 100
          - name: "Item B"
            value: 200
      as: item
      items:
        - title: "{{ item.name }}"
          content: "Value: {{ item.value }}"

Required Fields

Field Type Description
query object Data source with inline data array
as string Variable name for each iteration (accessed via {{ as.field }})
items list Layout items to generate per iteration

Behavior

  • Iterates over each row in query.data
  • Each row is bound to the variable specified in as
  • The items template is rendered for each row with Jinja templating
  • Generated items are inserted into the parent layout
  • Loop variables merge with parent variables (partials can access both)

Example: Dynamic Board Imports

rows:
  - foreach:
      query:
        data:
          - column: "revenue"
            type: "numeric"
          - column: "created_at"
            type: "date"
      as: col
      items:
        - partials/{{ col.type }}.yml  # Routes to different partials

For more examples and use cases, see Board Imports.

Comparison Table

Layout Type Best For Responsive Behavior Complexity
Rows Standard reports, mobile-first Stacks vertically (naturally) Low
Cols Side-by-side comparisons, sidebars Wraps to vertical stack on mobile Low
Grid Dense dashboards, precise control Reflows or scales based on config High
Tabs Reducing clutter, categorization Tab bar adapts (scrolls or menu) Medium
Details Collapsible sections, progressive disclosure Collapses to single row Low
Foreach Dynamic generation, data profiling Inherits parent layout behavior Medium

Best Practices

  1. Start with Rows: Most dashboards are effectively a stack of sections. Start with a rows layout and nest other layouts inside.
  2. Use Cols for comparisons: Place related metrics side-by-side for easy comparison.
  3. Limit Nesting: While Dataface supports infinite nesting, sticking to 2-3 levels usually produces the most maintainable and readable boards.
  4. Mobile Awareness: Remember that cols will stack on mobile. If you need elements to always be side-by-side (like small sparklines), consider a grid or a specific chart type instead.