Data and selection API

The small shared contracts behind datasets, filters, custom views and generated dashboards.

Dataset and field contracts

dataset(rows, overrides?) attaches schema metadata to rows. inferSchema(rows) infers that metadata, and resolveData(input) normalizes a rows array or Dataset. See Data model for inference and formats.

PropTypeDefaultDescription

kindrequired'dataset'——

rowsrequiredR[]——

schemarequiredSchema——

PropTypeDefaultDescription

namerequiredstring——

typerequired'quantitative' | 'temporal' | 'nominal' | 'boolean'FieldType——

labelrequiredstring—Human label for axes, legends and table headers.

formatrequiredFormatter——

axisFormatFormatter—Optional axis-only format; exact values retain format.

tooltipFormatFormatter—Optional tooltip-only format; table cells retain format.

descriptionstring—Plain-language definition or caveat, shown in supported tooltips and table headers.

timeZonestring—IANA time zone for instant-valued dates; date-only strings stay calendar dates.

currencystring—ISO 4217 code used by currency formats.

unitstring—Short unit badge shown on KPIs and cards, e.g. "USD" or "COUNT".

Selection hooks

useSelection(id?) subscribes to the nearest Selection or a named store. useSourceId(explicit?) creates a stable publisher identity. useLinkedRows(rows, options) filters rows while excluding the current view's own predicates.

PropTypeDefaultDescription

idstring—Name other components can address with useSelection(id). Defaults to a generated id.

onChange(predicates: Predicate[], event: SelectionEvent) => void—Called after every change with the full predicate list and the event that caused it.

childrenReactNode——

PropTypeDefaultDescription

idrequiredstring | null—Store id, or null when there is no enclosing Selection.

predicatesrequiredPredicate[]——

getrequired(field: string) => Predicate | undefined——

setrequired(field: string, value: Primitive | Primitive[] | [Primitive, Primitive] | undefined, opts?: SetOptions) => void——

togglerequired(field: string, value: Primitive, opts?: Omit<SetOptions, 'op'> & { multiple?: boolean }) => void——

clearrequired(field?: string) => void——

filterrequired(rows: readonly R[], exceptSource?: string) => R[]—Rows matching every predicate, optionally excluding those published by exceptSource.

PropTypeDefaultDescription

selectionstring | false—Selection id to read from; defaults to the nearest <Selection>. Pass false to opt out.

sourcerequiredstring—This component's publisher id; its own predicates are not applied to it.

Read the custom-view pattern before implementing a selection publisher.

Predicates

matches(row, predicate) evaluates one predicate. applyPredicates(rows, predicates) combines predicates with AND. describePredicate and predicateValueLabel produce labels for filter UI. The selection store adds the publishing source so a view can exclude its own predicate.

PropTypeDefaultDescription

fieldrequiredstring——

sourcestring—The component that published it. A view never filters itself by its own predicates.

labelstring—Optional human label, shown in FilterBar chips and selection logs.

oprequired'eq' | 'in' | 'between'——

valuerequiredPrimitive | Primitive[] | [Primitive, Primitive]——

PropTypeDefaultDescription

opPredicate['op']—Defaults to "eq" for a scalar, "in" for an array of values.

sourcestring——

labelstring——

Formatting

makeFormatter(format, options?) creates a reusable formatter. makeFieldFormatter(field, options?, override?) resolves value, axis or tooltip metadata; formatField(field, value, options?) formats one value. formatDelta(value, kind?, digits?, options?) formats signed changes using locale options. makeRangeFormatter and formatParts support ranges and structured presentation. Read Formatting and notation for precision, units, time zones, exact display limits and optional adapters.

PropTypeDefaultDescription

localestring——

currencystring——

timeZonestring——

shortboolean—Short automatic labels for axes. Explicit format objects retain their precision.

surface'value' | 'axis' | 'tooltip'——

Schema and renderer

validateSpec(input) returns validity and path-specific errors. validateFormat(input) checks a standalone serializable format, including Intl constructor constraints. SpecView renders a supported JSON spec using the datasets you provide. Read the spec guide for validation and the editor.

PropTypeDefaultDescription

specrequiredunknown—A component spec or a Dashboard, typically JSON from a model. Validated before rendering.

datarequiredRecord<string, DataInput>—Datasets the spec can reference by name.

classNamestring——

styleCSSProperties——

PropTypeDefaultDescription

validrequiredboolean——

errorsrequiredSpecError[]——

PropTypeDefaultDescription

pathrequiredstring—JSON Pointer to the offending value, e.g. "/layout/0/y". Empty for the root.

messagerequiredstring——

Report an issueBuilt Oct 21, 2026