Skip to main content
One section per primitive exported by snackapp.ui. Every example is a complete page module: paste it into a new file under pages/ of a project scaffolded by snackapp init and it runs against that project’s items and notes collections. The types a primitive renders come from the collection’s declared schema. The storage shape, the operands, and the renderer of each type are in the field-type reference.
A page function runs once per navigation, on the server, with real data in hand. What it returns is a tree, not HTML. Typing, sorting a loaded table, opening a modal, and switching a tab never call Python again; an @action does.

Layout

ui.header

A button passed to actions is moved into the header, so it renders once.

ui.row

Children wrap, and below 768px they stack.

ui.column

ui.card

ui.tabs

Takes no parameters. It holds ui.tab children and nothing else; switching one is client-local and calls no Python.

ui.tab

ui.fragment

A fragment is what replaces a whole-page rerun: an action names it and only this subtree is rebuilt. The collections read inside it become its dependencies, so a write to one refreshes it without being asked.

ui.grid

Below 768px it is one column.

ui.divider

Takes no parameters.

Display

ui.text

ui.markdown

ui.stat

Handed a Query, it issues an aggregate; the rows it counts never leave the database.

ui.badge

ui.empty

Data surfaces

Each of the four view types takes either a materialised list[dict], which is paged in the browser, or a Query, which is paged on the server: the page function registers it and the client fetches every page — the first one included — through /_sa/rows.

ui.table

A column’s type comes from the declared schema, so the renderer and the editor match the field type without the page repeating it. A single column opts out with {"field": ..., "editable": False}. Grouping comes from the URL, and each group gets its own cursor and its own count.

ui.list_view

This is also what a board or a calendar falls back to below 768px.

ui.kanban

With no on_move, a drop writes group_by through the record endpoint. The column count and the value_field sum are aggregates over the whole column, not over the cards that happen to be loaded; value_field must be a number, because the aggregate endpoint refuses sum() over a JSON column.

ui.calendar

date_field is checked against the declared schema when the page runs, so a calendar over a field that is not a date fails with the dated fields named rather than rendering nothing.

ui.fields

An editable grid needs one of collection or action, or it raises.

ui.record

A tab is "notes" — a collection that points back at this one — or a dict: {"collection": ..., "via": ..., "columns": [...], "label": ..., "row_link": ..., "page_size": ...} when the pointing field is ambiguous or is not a relation, or {"field": ...} to list the records a multi-relation on this record points at. Each tab’s count is an aggregate over the whole related set.

ui.timeline

Naming a collection and an id shows the framework’s own feed: what it wrote when the record was created and when a tracked field changed, plus the comments people added, newest first. Tracking is activity=True on the collection.

ui.chart

A chart over a query is one GROUP BY computed by the backend. Six widgets on a dashboard are six aggregates, not six scans.

ui.bar_chart

The minimal bars, for a series a page function already has. ui.chart is what aggregates.

View controls

ui.view_bar

The current view is whatever the address bar says, so switching is a navigation and the back button undoes it. With collection, the bar shows the defaults views= declares on the collection — which cannot be renamed or deleted — plus the personal and shared views the signed-in user can see, and saving, renaming, duplicating and deleting go through /_sa/views.

ui.filter_bar

Filters bind to the URL, not to hidden server state, so a filtered view is shareable and back-button correct. With collection, the filter, sort and group builders offer exactly the operands each field’s type declares, so a user cannot compose a filter the compiler would reject.

Input

ui.button

confirm is checked first, then opens, then link, then action.

ui.form

Draft state lives in the browser: Python never sees a keystroke. Without collection, a field with no declared type is a text box — which is how a url field ends up rejected by the backend on submit rather than by the editor on the way in.

ui.modal_form

The parameters are ui.form’s. The form is declared where the page wants it and stays closed until a ui.button(opens=name) reveals it; a successful submit closes it.

CSV

ui.import_csv

Upload, preview, map, validate, write — in that order. Nothing reaches the collection until the mapping is confirmed and every row validates, and the wizard refuses at the start for a user who cannot create in the target. Computed fields are not offered as targets.

ui.export_csv

The export is the view: the same query, narrowed by the same URL, streamed from the server a page at a time rather than assembled in the browser.