Interface: CreatePlayUIOptions
API / @xmachines/play-dom / CreatePlayUIOptions
Defined in: packages/play-dom/src/types.ts:67
Options for createPlayUI() — the batteries-included DOM factory.
Extends UIProviderOptions, which contributes functions,
validationFunctions, navigate, and onRenderError. All four are
closed over at factory creation time and forwarded into PlayRenderer
on every mount() call.
Parallel to PlayUIProvider’s props in the framework renderers.
See
createPlayUI
Extends
Properties
| Property | Type | Description | Inherited from | Defined in |
|---|---|---|---|---|
fallback? | HTMLElement | null | Optional fallback element shown when currentView is null on initial mount only. The fallback is appended immediately after mount() if the container is empty at that moment (i.e. the actor’s initial view is null). Limitation: If the actor’s view transitions to null after mount, the container will be cleared but this fallback will NOT be re-appended. For dynamic fallback behavior (null view after non-null), use PlayRenderer directly and wrap the actor.currentView signal to inject fallback content. | - | packages/play-dom/src/types.ts:79 |
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 const mount = createPlayUI(registryResult, { 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 | packages/play-dom/src/json-render/types.ts:88 |
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(); const mount = createPlayUI(registryResult, { navigate }); Spec binding that triggers navigation: { "on": { "click": { "action": "doSomething", "onSuccess": { "navigate": "/dashboard" } } } } | UIProviderOptions.navigate | packages/play-dom/src/json-render/types.ts:152 |
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 const mount = createPlayUI(registryResult, { onRenderError: (err, name) => { myErrorReporter.capture(err, { context: name }); }, }); | UIProviderOptions.onRenderError | packages/play-dom/src/json-render/types.ts:178 |
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 @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 "@json-render/core"; const mount = createPlayUI(registryResult, { 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 | packages/play-dom/src/json-render/types.ts:123 |