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, or another Nested Board, allowing for infinite recursion.

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

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

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.