JsonSchemaForm

API reference and demos for JsonSchemaForm.

Source

Import

import { JsonSchemaForm } from "@flanksource/clicky-ui/components";

Demos

Default · Open in Storybook

Presentation Extensions · Open in Storybook

Empty · Open in Storybook

The props table documents the component-specific surface. Standard DOM attributes inherited from React, such as className, event handlers, and accessibility attributes, may also be accepted when the component’s prop type extends a native element.

Props

Prop	Type	Default	Description
applyDefaults	boolean	true	Whether JSON Schema `default` keywords are materialized into the form value. Defaults to true: for a form that authors a new document, a default is part of the value (a defaulted discriminator selects its if/then branch), so the form commits it through onChange on first render. Set false when `value` is a source-of-truth document the form only edits — a YAML file, a saved record — where committing defaults the file never wrote silently rewrites it. Defaults are then neither rendered nor committed: the form shows exactly what the document holds.
autoSave	boolean	false	Drop the properties layout's per-field confirm step: leaving a field or pressing Enter commits it through `onChange`, and no check/cancel pair is rendered. Escape still reverts to the saved value. Use it when the form already sits behind a save of its own, so confirming each field twice buys nothing. Left off, an edit that loses focus is parked on the row — shown, unsaved, and waiting for the check. Only the `properties` layout has a draft to commit; `stacked` and `inline` send every keystroke straight to `onChange`, so this does nothing there.
errors	JsonSchemaFormError[]	[]	Authoritative server validation errors keyed by RFC 6901 JSON Pointer. Exact field matches render below their controls; root and unmatched errors render in the form summary.
expressionEvaluator	ExpressionEvaluator	—	Evaluates the `when.expr` of `x-on-change` listeners. The form has no built-in expression language; a schema that uses `expr` without this prop fails loudly instead of guessing.
hiddenKeys	string[]	—	Property keys to omit from rendering.
hideEmpty	boolean	false	Omit fields the value says nothing about, at every depth. For a record that is finished being edited — an audit view of a submitted form — the blanks are noise: they say only that a field existed, and a schema wide enough to describe many records can leave far more blank than filled. Empty means `undefined`, `null`, `""`, `[]` or `{}`. `false` and `0` are answers and always render. An object whose fields are all empty is itself empty and goes with them. For an editable form this is usually wrong: there, a blank field is the question.
hideReadOnlyFields	boolean	false	Omit fields whose schema declares `readOnly: true` entirely, instead of rendering them as read-only value displays. Applies at every depth.
idPrefix	string	—	Namespaces generated input/label ids (`jsf-<idPrefix>-<key>`). Set this when more than one form renders on the same page so their ids don't collide, which would otherwise break label/input focus association.
inline	boolean	false	Shorthand for `layout: { mode: "inline" }` (2-column label/value); stacked when false (default). Ignored when `layout` is provided.
instancePath	string	—	RFC 6901 path where this projected form is mounted in its full document.
layout	FormLayout	—	Form-level layout. Takes precedence over `inline`. Inline mode shrinks the label column to fit (capped/truncated at 40ch) and caps the value column at 600px. Properties mode renders a table with indented nested labels and click-to-edit values. The inline check saves the edit; cancel discards it. Leaving the field parks the edit instead — the row shows the pending value with the check and cancel still offered. See `autoSave` to commit instead.
lookupFetcher	LookupFetcher	—	Resolves options for `x-clicky-lookup` fields (async entity-reference pickers). When set, the form provides it to its lookup controls via context. Hosts typically build it from the operations api client's lookup endpoint.
onChange*	(…) => void	—	—
onRootChange	(…) => void	—	Atomically replaces the full extension root. Required by sibling edits.
persistPreferences	boolean	true	Persist menu selections to localStorage so they survive remounts. Defaults to true. When false the menu still adjusts the current instance, but nothing is read from or written to localStorage.
post	PostExtension[]	—	—
pre	PreExtension[]	—	—
preferencesStorageKey	string	clicky-ui-json-schema-form-preferences	localStorage key the display preferences are stored under. Defaults to a shared key, so by default every form shares one set of preferences; pass a distinct key to isolate a screen or form.
readOnly	boolean	false	—
requiredFirst	boolean	false	Render required fields before optional ones at every object level. The sort is stable: required keys keep their relative order, then optional keys keep theirs. Defaults to false (schema property order is preserved).
rootValue	Record<string, unknown>	—	Full document exposed to extensions when this form edits a projection.
schema*	JsonSchemaObject	—	—
showFilter	boolean	—	Show a persistent name/value filter above the form. Defaults to true for properties layout when display options are enabled, false otherwise. Matching nested content keeps its top-level group intact. Password values are excluded. Filtering never modifies the submitted values.
showPreferencesMenu	boolean	true	Show the top-right three-dot display-options menu (size, layout, and sort). Defaults to true. The menu controls only this form's appearance — never global page density or field values. When false the form renders exactly as before and performs no preference reads/writes.
size	enum	md	Scales every input and label form-wide. One of "xs" | "sm" | "md" | "lg" | "xl"; defaults to "md" (the original fixed sizing). Applies at every depth.
title	string	—	—
value*	Record<string, unknown>	—	—