Board Layouts¶

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

Rows (Vertical Stack)¶

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

title: "Sales Dashboard"

charts:
  revenue_by_category:
    query: _doc_examples.yaml#sales
    type: bar
    title: "Revenue by Category"
    x: category
    y: revenue
  orders_trend:
    query: _doc_examples.yaml#sales
    type: line
    title: "Orders Over Time"
    x: date
    y: units_sold
  products_breakdown:
    query: _doc_examples.yaml#sales
    type: pie
    title: "Product Breakdown"
    x: product
    y: revenue

rows:
  - revenue_by_category
  - orders_trend
  - products_breakdown

▶

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

Cols (Horizontal Stack)¶

Items are arranged horizontally, side-by-side.

title: "Comparison View"

charts:
  revenue:
    query: _doc_examples.yaml#sales
    type: bar
    title: "Revenue"
    x: product
    y: revenue
  orders:
    query: _doc_examples.yaml#sales
    type: line
    title: "Orders"
    x: date
    y: units_sold
  growth:
    query: _doc_examples.yaml#sales
    type: kpi
    title: "Total Revenue"
    metric: revenue

cols:
  - revenue
  - orders
  - growth

▶

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 x, y, width and height.

title: "Grid Dashboard"

charts:
  kpi1:
    query: _doc_examples.yaml#sales
    type: kpi
    title: "Total Revenue"
    metric: revenue
  kpi2:
    query: _doc_examples.yaml#sales
    type: kpi
    title: "Units Sold"
    metric: units_sold
  kpi3:
    query: _doc_examples.yaml#sales
    type: kpi
    title: "Categories"
    metric: category
  main_chart:
    query: _doc_examples.yaml#sales
    type: bar
    title: "Revenue by Product"
    x: product
    y: revenue
  data_table:
    query: _doc_examples.yaml#sales
    type: table
    title: "Sales Data"

grid:
  columns: 12
  items:
    - item: kpi1
      width: 4
    - item: kpi2
      width: 4
    - item: kpi3
      width: 4
    - item: main_chart
      width: 12
    - item: data_table
      width: 12

▶

Grid Features¶

Flow: Items without x,y fill the next available space
Pinning: Items with x,y are fixed to that position
Smart Sizing: Charts use natural default sizes based on type
Overlapping: Multiple items can occupy the same cells
Gap: The gap property controls structural spacing

Note: Sizing properties (width, height, x, y) 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.

title: "Multi-Tab Dashboard"

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

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

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

    - title: "Details"
      rows:
        - details

▶

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

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

Boards Overview - Basic board structure
Sizing - Width and height control
Examples - Complex layout patterns