Building a dashboard.

Pin a cell, drag it where you want, repeat. A dashboard is a layout over the work you've already done — no separate definitions, no extra modeling layer.

Pin a cell

Right-click any cell in a notebook — chart, SQL, code, markdown — and pick Pin to dashboard. The first time you do this in a project, Orchid creates a fresh dashboard.orchid in the project root and adds the cell as the first tile. Subsequent pins ask which dashboard to append to.

Tiles store a pointer to the source cell, not a copy of its output. Open the dashboard and the tile fetches the cell's current output from its notebook.

The right-click menu on a chart cell showing the Pin to dashboard option./docs-images/dashboards/pin-menu.png
Right-click → Pin to dashboard. Pick which dashboard.

The dashboard file

Dashboards are .orchid-dashboard YAML files. They show up in the sidebar with a small grid icon, separated from notebooks. The file is YAML, so it diffs cleanly and merges by hand when it has to.

orchid_dashboard: '1.0'
metadata:
  title: Q1 review
  created: '2026-05-14T09:00:00Z'
tiles:
  - id: t1
    type: kpi
    source:
      kind: notebook_block
      notebook_id: revenue.orchid
      block_id: total_revenue
    layout: { x: 0, y: 0, w: 3, h: 2 }
  - id: t2
    type: chart
    source:
      kind: notebook_block
      notebook_id: revenue.orchid
      block_id: chart_by_month
    layout: { x: 3, y: 0, w: 9, h: 5 }

Arrange tiles

The dashboard grid is 12 columns wide. Drag a tile by its header to move it; drag any edge or corner to resize. Hold Shift and click to multi-select, then use the toolbar to align edges or distribute spacing evenly.

Tiles snap to the grid. You can stack rows as deep as you want — the dashboard scrolls vertically when it runs out of fold.

Tip

Start with the KPI strip at the top, the headline chart underneath, and detail tiles below the fold. Viewers see the summary first; the deep cuts wait for them to scroll.

Live-link to the source cell

Tiles stay linked to the cell they were pinned from. Three useful consequences:

  • Edit the SQL, re-run, the tile updates. No re-pinning needed.
  • Click the tile's overflow menu → Open source to jump straight back into the cell that produced it.
  • Delete the source cell and the tile shows a warning. You can re-pin or remove the orphaned tile from the dashboard.
A tile’s overflow menu with Open source, Refresh, and Remove options./docs-images/dashboards/tile-overflow.png
Every tile knows the cell it came from.

Refreshing tiles

A tile shows its source cell's last output. To refresh, re-run the source cell — from the notebook, or click Refresh in the tile's overflow menu (which jumps to the notebook and re-runs the cell for you).

Refresh all in the dashboard toolbar re-runs every source cell in dependency order. Useful for a Monday-morning "catch up the whole view" pass.

Renaming & reordering

Each tile has its own title and subtitle, separate from the source cell's id. Click the tile header to edit them — the dashboard reads better when titles match how you actually talk about the numbers.

Up next: Tile types, Filters, and Sharing. Back to the Dashboards overview.