Skip to content

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
Sales Dashboard 020k40k60k80k100k120k140k160k180k200kElectronicsAccessoriesToolsRevenue by Category1 Jan20242 Jan3 Jan4 Jan5 Jan6 Jan7 Jan8 Jan9 Jan10 Jan11 Jan12 Jan13 Jan14 Jan15 Jan16 Jan17 Jan18 Jan19 Jan20 Jan21 Jan22 Jan23 Jan24 Jan25 Jan26 Jan27 Jan28 Jan29 Jan30 Jan05001kOrders Over Time17% Widget B75,40415% Gadget Y68,40014% Widget A62,07014% Gadget X60,72413% Widget C59,72511% Tool Z48,80010% Tool A44,520Product Breakdown Data as of 16:49 UTC on 5 Aug 2026 made with dataface
▶

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
Comparison View 010k20k30k40k50k60k70k80kWidget BGadget YWidget AGadget XWidget CTool ZTool AGadget ZRevenue1 Jan20242 Jan3 Jan4 Jan5 Jan6 Jan7 Jan8 Jan9 Jan10 Jan11 Jan12 Jan13 Jan14 Jan15 Jan16 Jan17 Jan18 Jan19 Jan20 Jan21 Jan22 Jan23 Jan24 Jan25 Jan26 Jan27 Jan28 Jan29 Jan30 Jan05001kOrders440k Total Revenue Data as of 16:49 UTC on 5 Aug 2026 made with dataface
▶

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 Dashboard 440k Total Revenue 15k Units Sold 3 Categories 05k10k15k20k25k30k35k40k45k50k55k60k65k70k75k80kWidget BGadget YWidget AGadget XWidget CTool ZTool AGadget ZRevenue by Product Sales DataDateRegionProductCategoryRevenueUnits Sold26 Jan 2024EastWidget AElectronics1.5K5014 Jan 2024EastGadget YAccessories3K10013 Jan 2024NorthWidget BElectronics1.46K5210 Jan 2024EastWidget CElectronics1.25K5023 Jan 2024EastWidget AElectronics2.16K7229 Jan 2024EastWidget AElectronics3.6K12029 Jan 2024EastGadget YAccessories1.89K6319 Jan 2024SouthWidget BElectronics1.4K5016 Jan 2024EastGadget XAccessories2.24K665 Jan 2024SouthWidget BElectronics6162213 Jan 2024NorthGadget YAccessories2.01K675 Jan 2024EastWidget CElectronics3.2K12825 Jan 2024NorthWidget AElectronics1.26K4220 Jan 2024WestWidget AElectronics1.05K35 ‹ 1 2 … 18 › Data as of 16:49 UTC on 5 Aug 2026 made with dataface
▶

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
  • Default span: default_width/default_height on the grid: block set the column/row span applied to any item that doesn't specify its own width/height

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
Multi-Tab Dashboard Overview Trends Details Overview 010k20k30k40k50k60k70k80k90k100k110k120k130k140k150k160k170k180k190k200k210kElectronicsAccessoriesToolsSummary Chart Data as of 16:49 UTC on 5 Aug 2026 made with dataface
▶

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
Dashboard with Details 010k20k30k40k50k60k70k80k90k100k110k120k130k140k150k160k170k180k190k200k210kElectronicsAccessoriesToolsRevenue Summary▶Show Raw Data Data as of 16:49 UTC on 5 Aug 2026 made with dataface
▶

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