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.

source: examples_db
title: "Sales Dashboard"

queries:
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
  sales_by_date:
    sql: |
      SELECT date, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date ORDER BY date
  sales_by_product:
    sql: |
      SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC

charts:
  revenue_by_category:
    query: sales_by_category
    type: bar
    title: "Revenue by Category"
    x: category
    y: revenue
  orders_trend:
    query: sales_by_date
    type: line
    title: "Orders Over Time"
    x: date
    y: units_sold
  products_breakdown:
    query: sales_by_product
    type: pie
    title: "Product Breakdown"
    theta: revenue
    color: product

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.

source: examples_db
title: "Comparison View"

queries:
  sales_by_product:
    sql: |
      SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
  sales_by_date:
    sql: |
      SELECT date, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date ORDER BY date
  sales_summary:
    sql: |
      SELECT SUM(revenue) AS revenue, SUM(units_sold) AS units_sold, COUNT(DISTINCT category) AS category_count FROM ecommerce_orders

charts:
  revenue:
    query: sales_by_product
    type: bar
    title: "Revenue"
    x: product
    y: revenue
  orders:
    query: sales_by_date
    type: line
    title: "Orders"
    x: date
    y: units_sold
  growth:
    query: sales_summary
    type: kpi
    label: "Total Revenue"
    value: 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.

source: examples_db
title: "Grid Dashboard"

queries:
  sales_summary:
    sql: |
      SELECT SUM(revenue) AS revenue, SUM(units_sold) AS units_sold, COUNT(DISTINCT category) AS category_count FROM ecommerce_orders
  sales_by_product:
    sql: |
      SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
  sales:
    sql: |
      SELECT * FROM ecommerce_orders

charts:
  kpi1:
    query: sales_summary
    type: kpi
    label: "Total Revenue"
    value: revenue
  kpi2:
    query: sales_summary
    type: kpi
    label: "Units Sold"
    value: units_sold
  kpi3:
    query: sales_summary
    type: kpi
    label: "Categories"
    value: category_count
  main_chart:
    query: sales_by_product
    type: bar
    title: "Revenue by Product"
    x: product
    y: revenue
  data_table:
    query: sales
    type: table
    title: "Sales Data"

grid:
  columns: 24
  items:
    - item: kpi1
      width: 8
    - item: kpi2
      width: 8
    - item: kpi3
      width: 8
    - item: main_chart
      width: 24
    - item: data_table
      width: 24

▶

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.

source: examples_db
title: "Multi-Tab Dashboard"

queries:
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
  sales_by_date:
    sql: |
      SELECT date, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY date ORDER BY date
  sales:
    sql: |
      SELECT * FROM ecommerce_orders

charts:
  summary:
    query: sales_by_category
    type: bar
    title: "Summary Chart"
    x: category
    y: revenue
  revenue_trend:
    query: sales_by_date
    type: line
    title: "Revenue Trend"
    x: date
    y: revenue
  orders_trend:
    query: sales_by_date
    type: line
    title: "Orders Trend"
    x: date
    y: units_sold
  details:
    query: 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

---

Details (Collapsible Sections)

Any nested board item can be made collapsible by adding details. This renders a clickable summary bar that expands/collapses the content — no JavaScript needed.

source: examples_db
title: "Dashboard with Details"

queries:
  sales_by_category:
    sql: |
      SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
  sales:
    sql: |
      SELECT * FROM ecommerce_orders

charts:
  summary:
    query: sales_by_category
    type: bar
    title: "Revenue Summary"
    x: category
    y: revenue
  breakdown:
    query: sales
    type: table
    title: "Full Data"

rows:
  - summary

  - details:
      summary: "Show Raw Data"
      expanded_title: "Hide Raw Data"
    rows:
      - breakdown

▶

Use details when: - Hiding secondary content behind a toggle - Reducing dashboard clutter - Progressive disclosure of complex data

---

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
Details	Collapsible sections, progressive disclosure

---

Related

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