Interface: PlayDomOptions
API / @xmachines/play-dom / PlayDomOptions
Defined in: packages/play-dom/src/types.ts:23
The options of PlayRenderer.
This type extends UIProviderOptions, which gives functions,
directives, validationFunctions, navigate, and onRenderError. Each render
pass puts all of them into DomRenderContext, and a component implementation
reads them at ctx.ctx.*.
Extends
Properties
| Property | Type | Description | Inherited from | Defined in |
|---|---|---|---|---|
directives? | DirectiveDefinition<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>[] | Custom directives — user-defined $-prefixed dynamic values that extend the spec expression language (e.g. { $format: "currency", value: ... }). Each entry is a DirectiveDefinition built with defineDirective from @xmachines/json-render-core. The array is converted to a DirectiveRegistry once per render pass and forwarded to resolveElementProps via PropResolutionContext.directives. Built-in expressions ($state, $cond, etc.) always take precedence over custom directives. Mirrors the directives prop on JSONUIProvider / JsonUIProvider introduced in Json-render 0.19. Example import { defineDirective, resolvePropValue } from "@xmachines/json-render-core"; import { z } from "zod"; const formatDirective = defineDirective({ name: "$format", description: "Locale-aware number formatting.", schema: z.object({ $format: z.enum(["number", "currency"]), value: z.unknown() }), resolve(value, ctx) { const resolved = resolvePropValue(value.value, ctx); return new Intl.NumberFormat().format(resolved as number); }, }); renderSpec(spec, store, registry, { directives: [formatDirective] }); | UIProviderOptions.directives | - |
functions? | Record<string, ComputedFunction> | Named compute functions for { $computed: "name", args: {...} } prop expressions. Each function receives the resolved args object and returns the computed value. Forwarded directly to resolveElementProps via PropResolutionContext.functions, matching the FunctionsContext provider in the framework renderers. Without this option, $computed expressions resolve to undefined (no throw). Example renderSpec(spec, store, registry, { functions: { fullName: (args) => ${args.first} ${args.last}, formatCurrency: (args) => new Intl.NumberFormat().format(args.amount as number), }, }); Mirrors the functions prop on JSONUIProvider / JsonUIProvider. | UIProviderOptions.functions | - |
loading? | boolean | With the value true, the spec is still streaming, for example from an AI provider. The renderer gives the flag to renderSpec. A component implementation therefore reads ctx.ctx.loading, and it can render a skeleton state. The flag also stops each warning about an absent child during the ingestion of the stream, because an element of a reference can still be absent from the incremental spec. This option matches the loading prop of the framework renderer providers. | - | packages/play-dom/src/types.ts:54 |
navigate? | (path) => void | Programmatic navigation function. Called automatically when an action binding resolves with onSuccess: { navigate: "/path" }. The resolved path string is passed as the sole argument. Mirrors the navigate prop in ActionProvider from the framework renderers, where it is captured in the execute() closure. Also available to component implementations directly via ctx.ctx.navigate for cases where navigation needs to be triggered outside of an action binding. Example import { useNavigate } from "my-router"; const navigate = useNavigate(); renderSpec(spec, store, registry, { navigate }); Spec binding that triggers navigation: { "on": { "click": { "action": "doSomething", "onSuccess": { "navigate": "/dashboard" } } } } | UIProviderOptions.navigate | - |
onConfirm? | ConfirmHandler | Confirmation hook for actions that declare confirm in their binding. Consulted by emit() before executing a confirm-gated action. Return (or resolve) true to execute, false to skip. Without this handler, confirm-gated actions are skipped with a console.warn — they never execute unconfirmed. See ConfirmHandler for the full contract. This is the headless equivalent of the pendingConfirmation / confirmAction() / cancelAction() flow in the framework adapters. | UIProviderOptions.onConfirm | - |
onRenderError? | RenderErrorHandler | Unified error handler for component render errors and action handler rejections. Matches RenderErrorHandler = (error: unknown, name: string) => void. Invoked for three distinct error classes: - (error, elementType) — when a component renderer throws synchronously during renderSpec - (error, actionName) — when an action handler rejects during emit() (on-event path) - (error, actionName) — when an action handler rejects during a watch binding callback When provided, suppresses the console.error fallback for all three error types. Forwarded into renderSpec as the onRenderError parameter and into DomRenderContext.onRenderError so both emit() and watch handlers route their errors through the same channel as component render errors. Example renderSpec(spec, store, registry, { onRenderError: (err, name) => { myErrorReporter.capture(err, { context: name }); }, }); | UIProviderOptions.onRenderError | - |
registryResult? | DefineRegistryResult | The result of defineRegistry. It gives the registry and the factory of the handlers. With this option, PlayRenderer connects setState and getState of the StateStore on @xstate/store to the factory of the handlers for you. This is the preferred way, because each action then always receives a live setState and a live state on the current store. | - | packages/play-dom/src/types.ts:32 |
store? | StateStore | The optional external StateStore, for example from xstateStoreStateStore in @xmachines/json-render-xstate. With this option, PlayRenderer works in the controlled mode: it ignores spec.state, and this store is the single source of truth of the UI state, such as a form value. Without this option, the renderer makes a new @xstate/store atom for each view transition, with the values of spec.state. | - | packages/play-dom/src/types.ts:42 |
validationFunctions? | Record<string, (value, args?) => boolean> | Custom validation functions for inline field validation. Each function receives (value, args?) and returns true (valid) or false (invalid). Functions are available to component implementations via ctx.ctx.validationFunctions and should be passed as customFunctions to runValidationCheck / runValidation from @xmachines/json-render-core. Mirrors customFunctions in ValidationProvider from the framework renderers. The DOM renderer has no automatic ValidationProvider tree — validation must be invoked explicitly by component implementations. Example import { runValidationCheck } from "@xmachines/json-render-core"; renderSpec(spec, store, registry, { validationFunctions: { isEven: (value) => typeof value === "number" && value % 2 === 0, phoneNumber: (value) => /^\+?[\d\s\-()]{7,}$/.test(String(value)), }, }); // Inside a ComponentFn: const MyField: ComponentFn<typeof catalog, "MyField"> = ({ ctx }) => { const result = runValidationCheck( { type: "isEven", message: "must be even" }, { value: someValue, stateModel: {}, customFunctions: ctx.ctx.validationFunctions }, ); // result.valid, result.message }; | UIProviderOptions.validationFunctions | - |