# Dashboard composition blocks _Every block the dashboard composer can create, including required inputs, data bindings, output behaviour, and layout settings._ Canonical: https://snoze.dev/help/dashboard-widgets/ The dashboard composition vocabulary is the safe, semantic input used by the assistant and dashboard tools. Snoze compiles each entry into the ordinary page block model. It intentionally omits persisted block IDs, order keys, and raw manifests. Every composition block can have a 12-column-grid `layout` and an optional tab name. Layout stores column, row, width, and height. Embed blocks can set `restrictAccess`; when true, a viewer must also be allowed to read the target. Canonical contract values: - `heading` - `text` - `divider` - `insight` - `database_view` - `metric` - `data` - `doc` - `agenda` - `clock_in` - `timesheet` - `page_link` - `activity_feed` - `button` - `form_embed` - `drive_embed` - `control` - `template_text` ## Composition blocks ### Heading `heading` A dashboard heading. Set visible `text` and optional level 1, 2, or 3, horizontal alignment, and vertical alignment. `content` is accepted only as a repair-friendly alias for text. It compiles to the matching page heading kind. ### Text `text` An ordinary paragraph with horizontal and vertical alignment. Use `text` for the visible copy; `content` is a compatibility alias. This is static copy, not parameter interpolation. ### Divider `divider` A horizontal or vertical separator with grid placement. It carries no text or data binding and compiles to a Divider page block. ### Insight `insight` A durable briefing with required title, optional body, original prompt, and source workspace item IDs. `content` is a compatibility alias for body. Refreshing an insight replaces stored block content rather than computing a different answer for every viewer. It may restrict access to the sources. ### Database view `database_view` An inline database layout. `databaseId` is required; `viewId`, `viewKind`, and owned `viewConfig` select or describe its presentation. `paramFilters` map dashboard parameter names to database fields, while `selectionParam` lets the widget expose its selected record to other blocks. The target database's permissions still apply. ### Metric `metric` The earlier single-database number or chart: a required database and optional saved view, with `count`, `sum`, `avg`, `min`, or `max` (`fieldKey` for all but count) and a number, column, bar, line, or pie display. It still compiles and renders; new dashboards use `data` instead. ### Data `data` A data widget in the current metrics model. `widget` holds the series (which metrics to plot, by id from the dashboard's `metrics` or the widget's own), the grouping (a time grain, a field, or a shared field), an optional split, period and comparison overrides, sort, a top-N limit, whether empty groups show, and the visual: KPI, line, area, column, bar, combo, donut, funnel, waterfall, table, leaderboard, progress, gauge, or heatmap with its options. An optional `title` names the card; without one it is named after its metrics. ### Doc `doc` Rich text inside a card. Give either `markdown` — headings, lists, to-dos, quotes, code, and tables are converted into document blocks — or `blocks`, a list of semantic entries (kind, text, code and language, caption, checked state, and the index of a parent block for nesting). Only the block kinds a Doc can hold are accepted, up to 300 blocks. Snoze generates block ids and ordering. ### Agenda `agenda` Upcoming calendar events for the viewer, over `today`, `this_week`, `next_7_days`, or `next_30_days`. ### Clock in `clock_in` Clock in and out for the viewer, with the running timer. Needs time tracking. ### Timesheet `timesheet` Tracked hours for `this_week`, `last_week`, `this_month`, or `last_7_days`, for the viewer (`me`) or the `team`. Needs time tracking. ### Page link `page_link` A preview card for a required workspace `itemId`. It opens that item and may restrict access. It does not copy or snapshot the target. ### Activity feed `activity_feed` Recent workspace activity, optionally capped with `limit`. It has no event-type filter in the composition contract and is not a replacement for full event history. ### Button `button` A required label plus either a saved Action reference or a local command. Local commands can open an item, set a dashboard parameter, or open a dashboard tab. Legacy inline button actions are not part of the composition vocabulary. ### Form embed `form_embed` An inline Form selected by required workspace item ID. It uses the Form's own database, question, validation, step, and public settings and may restrict access. ### Drive embed `drive_embed` A workspace drive browser. An optional `folderId` chooses its starting folder; without one it starts at the root. The browser owns navigation after it opens and may restrict access. ### Control `control` An input that writes a required named dashboard parameter. The control style can be select, search, date, member, segmented, or toggle and can have a label and placeholder. Creating a Control does not bind other widgets automatically: their parameter filters or templates must name the same parameter. ### Template text `template_text` Dynamic presentation copy with a required template string and optional alignment. The compiler resolves the template's supported dashboard tokens; it does not treat the string as HTML or arbitrary code. ## Dashboard data Create and edit requests can also carry the dashboard's own data. `metrics` is the metric library every `data` widget can plot: aggregates over a database or Snoze app, or formulas over other metrics, such as `[Revenue] - [Expenses]`. `sharedFields` name one concept — Client, Owner — and the field that holds it in each source, so a single grouping or filter lines several databases up. `filters` sets the filter bar: the default period and comparison and which shared fields appear as filters. Unknown metric references and formula cycles are rejected before anything is saved, and an edit that omits these fields keeps the existing ones. ## Parameters and tabs Dashboard-level `params` declare the shared inputs Controls and data blocks use. Tabs declare named sections; a block's `tab` value assigns it to one. Parameter bindings are explicit and field-specific, so one owner selector can filter several widgets differently without changing their underlying saved views. For every persisted block kind, including blocks that the semantic composer does not expose, see [Page block types](https://snoze.dev/help/page-blocks/).