Dynamic UI SDK

The Dynamic UI SDK is the typed authoring surface for record forms, page UI blocks, and PDF document layouts. Your code returns a tree of supported components, and the platform renderer handles the rest.

Authoring Pattern

Each UI codeblock exports run() and returns SDK.GlobalStore(...).

Prefer destructuring components from SDK and using capitalized JSX values such as Flex, Text, and CollectionTable inside the returned tree.

import { Params, ReturnType } from './data';
import { SDK } from './external';

export function run(params: Params): ReturnType {
	const { Badge, CollectionTable, Flex, Text } = SDK;

	return SDK.GlobalStore({
		data: {
			selectedStatus: 'active'
		},
		ui: (store) => (
			<Flex direction="column" gap={4}>
				<Text textStyle="h2" content="Operations overview" />
				<Badge content={store.read('data.selectedStatus')} />
				<CollectionTable collectionName="projects" title="Projects" />
			</Flex>
		)
	});
}

Store API

The store object supports four core patterns:

1. store.bind(path)
2. store.read(path)
3. store.read(expr, { mode: 'CEL' })
4. store.derive(pointer, expression)

Scoped Callbacks

When a component introduces a nested item or row scope, use the typed callback that component provides instead of manually re-resolving paths.

• Repeater.items((item) => ...)
• DataGrid.columns((row) => [...])
• CollectionTable.details((row) => ...)
• Kanban.details((row) => ...)

import { Params, ReturnType } from './data';
import { SDK } from './external';

export function run(_params: Params): ReturnType {
	const { DataGrid, Flex, FormInput, GridColumn, Repeater, Text } = SDK;

	return SDK.GlobalStore({
		data: {
			items: [{ sku: 'A-1', qty: 1 }],
			rows: [{ name: 'Ada', qty: 2 }]
		},
		ui: (store) => (
			<Flex direction="column" gap={4}>
				<Repeater
					value={store.bind('data.items')}
					items={(item) => <FormInput label="SKU" value={item.bind('sku')} />}
				/>
				<DataGrid
					value={store.bind('data.rows')}
					columns={(row) => [
						<GridColumn header="Name" cell={<FormInput label="Name" value={row.bind('name')} />} />,
						<GridColumn header="Qty" cell={<Text content={row.read('qty')} />} />
					]}
				/>
			</Flex>
		)
	});
}

CEL in Dynamic UI

Use CEL for:

• visibility rules,
• dynamic props,
• derived values,
• pre_query expressions that depend on current scope.

Validation Behavior

Dynamic UI includes meaningful validation, especially in preview and invariant-check flows. Normal runtime rendering is intentionally lighter so page and form execution stays fast.

Components

Dynamic UI supports a broad but controlled registry of components, including:

• Layout and content: Flex, Text, Badge, Image, Divider, Chart
• Form components: FormInput, FormButton, Combobox, Checkbox, CheckboxGroup
• Structured views: Tabs, Steps, TreeView, DropdownMenu
• Data surfaces: DataGrid, Repeater, Table, CollectionTable, TaskBlock, Kanban, Timeline
• PDF layout: Document, Page, View

Supported Chart Types

The current chart component supports four chart kinds:

• bar: Compare values across categories. Provide cartesian data, an `xKey`, and one or more `series`. Use `stacked` when multiple series should accumulate.
• line: Show trends over time or ordered sequences. Provide cartesian data with an `xKey` and `series`. Use `curve` when you want linear, natural, or step rendering.
• area: Show trend plus volume emphasis. Use the same cartesian shape as bar and line charts. This works well when totals or stacked accumulation matter visually.
• donut: Show part-to-whole composition. Provide `data` as `{ key, value }[]` and use `innerRadius` to tune the center opening.

All chart specs also support shared metadata such as title, description, config, showLegend, showTooltip, showGrid, and valueFormat.

import { Params, ReturnType } from './data';
import { SDK } from './external';

export function run(_params: Params): ReturnType {
	const { Chart } = SDK;

	return SDK.GlobalStore({
		data: {},
		ui: () => (
			<Chart
				spec={{
					kind: 'bar',
					title: 'Projects by status',
					xKey: 'status',
					series: ['count'],
					data: [
						{ status: 'Active', count: 12 },
						{ status: 'Blocked', count: 3 },
						{ status: 'Done', count: 9 }
					],
					config: {
						count: { label: 'Projects' }
					}
				}}
			/>
		)
	});
}

Full Registry Reference

The list below covers the current authoring surface exposed by Dynamic UI, plus the one system-rendered placeholder you may encounter at runtime.

Layout and Content

Form Components

Structured and Stateful UI

Data Surfaces

PDF Layout Elements

System-Rendered Element

Form Surfaces vs Page Surfaces

Use form_for when the UI is tied to a collection-backed record form. Use a plain data store when building a page surface or PDF document that is not itself the primary mutation form.

Recommended Patterns

• Start with a small tree and expand only when the workflow clearly needs it.
• Use collection-backed forms for actual record editing.
• Use page UI blocks for dashboards, contextual browsing, and embedded operational components.
• Test with the real permission model, especially where redaction is involved.