# Dashboards basics

_Widgets, charts, and live external data._

Canonical: https://snoze.dev/help/dashboards-basics/

A dashboard is an operating surface, not a document — a grid of widgets that
turns your data into something you can read and act on at a glance. Where a
page is for writing and a database is for storing, a dashboard is for watching.

## View mode and edit mode

Dashboards open in **view mode**: a clean screen with no editing chrome, where
the data stays interactive — you can open a record or switch a tab inside an
embedded view without changing the dashboard itself. Building happens in an
explicit **edit mode** you toggle from the header. In edit mode you get a grid
canvas with an inspector panel on the right: click a widget to select it, and
all of its configuration lives in that panel. Edit mode is permission-gated, so
viewers never even see the toggle.

## Widgets

Every widget binds to your workspace data and picks how to show it:

- **Numbers and charts** — a KPI, line, area, column, bar, donut, funnel,
  waterfall, table, leaderboard, progress bar, gauge, or heatmap. Each plots
  one or more metrics, grouped by date, by a field, or by a shared field.
- **Doc** — a small document: headings, lists, to-dos, tables, and code, with
  the `/` menu and Markdown paste.
- **Agenda, clock-in, and timesheet** — your calendar and time tracking,
  right on the dashboard.
- **Database view** — a live embedded table, board, or chart from one of your databases.
- **Activity feed** — recent, member-meaningful events across the workspace.
- **Insight** — a durable written brief you or the AI can refresh.
- **Button** — runs a real workspace action, like refreshing a source or creating a record.

Add widgets from the gallery — its **Suggested** tab builds ready widgets from
your own databases — then drag to reposition and pull the edges to resize. The
[build a dashboard](https://snoze.dev/help/build-a-dashboard/) walkthrough takes you from an
empty grid to a working overview.

## Metrics, formulas, and shared fields

A **metric** is one number defined once: count, sum, average, median, minimum,
maximum, or latest value over a database or a Snoze app such as time entries,
with an optional filter. A **formula** combines metrics, even from different
databases — `[Revenue] - [Expenses]` is a profit metric across two tables.
Metrics live in the dashboard's **Data** panel, so every widget that shows
Revenue shows the same Revenue.

A **shared field** is one concept matched in several databases — Client in
Invoices and in Expenses — so one filter or grouping lines them all up. The
filter bar above the widgets sets the period, the comparison (previous period
or last year), and shared-field filters; what a viewer picks there is theirs
alone.

## Where the data comes from

Widgets only read Snoze state — your databases, views, aggregates, and events —
so dashboards stay fast and update in real time as the underlying data changes.
External services reach a dashboard by syncing into a database first, never by
a widget calling an API live. That's what keeps a dashboard responsive even
when the original source is slow. See [connect external
data](https://snoze.dev/help/connect-external-data/).

## Building with AI

The dashboard header has an **Ask AI** action. It inspects the current layout,
explains a proposed plan, and waits for your go-ahead before applying any
change — it uses the same workspace parts a person does, so nothing bypasses
permissions or history.

> [!TIP]
> Start with three widgets: one number that tells you whether things are OK,
> one chart for the trend, one list of what needs action. Add more only when a
> real question keeps going unanswered.

Dashboards share like any other item — with the team, or [published to the
web](https://snoze.dev/help/share-with-a-public-link/) for stakeholders who just need the
numbers.

## Go deeper

- [Build a dashboard](https://snoze.dev/help/build-a-dashboard/) — a full walkthrough from empty grid to live overview.
- [Connect external data](https://snoze.dev/help/connect-external-data/) — sync outside services into your databases.