Board Sizing¶

Dataface uses a "smart sizing" system that automatically divides space among items.

Default Behavior¶

Width Rule¶

All items in a layout split the available width evenly: - In a cols layout with 2 items, each gets 50% - In a cols layout with 3 items, each gets 33.3%

Height Rule¶

Heights are derived from width ÷ aspect ratio for plot-style charts (bar, line, area, etc.). The global default aspect ratio is chart.aspect_ratio in default_config.yml (default: 1.5, i.e. 3:2). Some chart types override this — for example, pie and arc default to 1.0 (square), and map types default to 1.2.

Exceptions (not aspect-ratio-driven):

KPI — fixed compact height (100px default)
Table — data-driven height based on actual row count
Spark bar — fixed height

The derived height is clamped between chart.min_height (150px) and chart.max_height (800px).

In a cols layout, all items share the same height (the tallest item's height).

Unequal Widths with Nesting¶

Use nested lists as a shorthand for nested boards. A nested list automatically inherits the layout type (rows or cols) of its parent.

50% / 25% / 25% Split¶

To make the first chart take up half the width (50%) and the next two share the remaining half (25% each), nest them in a list:

title: "Asymmetric Layout"

charts:
  main_chart:
    query: _doc_examples.yaml#sales_by_category
    type: bar
    title: "Main Chart (50%)"
    x: category
    y: revenue
  kpi1:
    query: _doc_examples.yaml#sales_summary
    type: kpi
    label: "Side Chart 1 (25%)"
    value: revenue
  kpi2:
    query: _doc_examples.yaml#sales_summary
    type: kpi
    label: "Side Chart 2 (25%)"
    value: units_sold

# 50% / 25% / 25% split using nested cols
cols:
  - main_chart
  - cols:
      - kpi1
      - kpi2

▶

Complex Nesting¶

title: "Complex Dashboard"

charts:
  kpi1:
    query: _doc_examples.yaml#sales_summary
    type: kpi
    label: "Revenue"
    value: revenue
  kpi2:
    query: _doc_examples.yaml#sales_summary
    type: kpi
    label: "Units Sold"
    value: units_sold
  mini1:
    query: _doc_examples.yaml#sales_by_category
    type: bar
    title: "Mini Chart 1"
    x: category
    y: revenue
  mini2:
    query: _doc_examples.yaml#sales_by_product
    type: bar
    title: "Mini Chart 2"
    x: product
    y: units_sold
  main:
    query: _doc_examples.yaml#sales_by_date_category
    type: line
    title: "Main Analysis"
    x: date
    y: revenue
    color: category

rows:
  - cols:
      - kpi1
      - kpi2
      - cols:
          - mini1
          - mini2
  - main

▶

Explicit Sizing¶

Height on Rows¶

Set explicit height on row items:

rows:
  - height: "120px"
    cols:
      - kpi1
      - kpi2
      - kpi3

  - main_chart  # Takes remaining height

Grid Sizing¶

In grid layouts, use width and height on items:

grid:
  columns: 24
  items:
    - item: kpi1
      width: 8      # 8 of 24 columns
    - item: kpi2
      width: 8
    - item: main_chart
      width: 16
      height: 2     # 2 rows tall
    - item: sidebar
      width: 8
      height: 2

Sizing Patterns¶

KPI Row + Main Chart¶

rows:
  - height: "100px"
    cols: [kpi1, kpi2, kpi3]
  - main_chart

cols:
  - cols:           # 66% main content
      - chart1
      - chart2
  - sidebar_chart   # 33% sidebar

Header + Body + Footer¶

rows:
  - height: "80px"
    text: "# Dashboard Title"
  - main_content    # Flexible middle
  - height: "60px"
    text: "Footer text"

Configuration¶

The following keys in default_config.yml (or your project's dataface.yml) control sizing:

Key	Default	Description
`style.charts.aspect_ratio`	`1.5`	Global width:height ratio for plot-style charts
`style.charts.min_height`	`150`	Minimum chart height (px)
`style.charts.max_height`	`800`	Maximum chart height (px)
`style.charts.height`	`300`	Fallback height when width is unknown
`style.charts.<type>.aspect_ratio`	—	Per-type override (e.g. `pie: 1.0`, `map: 1.2`)

Boards Overview - Basic board structure
Layouts - Layout types
Examples - Complex layout patterns