Schema Builder React component for Tailwind CSS v4
v1.0.0Added in 1.4.0
A React JSON schema builder for extraction schemas: named fields with unique keys, field and JSON types, required flags, nesting and a JSON view.
Each row of the table is a field: Name (the label people read), Unique key, Type (the JSON type it stores, as a badge), a Required switch (a red asterisk marks required names) and Description. The Field type (the control a form shows: text, date, currency, select, address...) is set in Edit details and shown on phone cards. Typing a Name fills the key with its slug (Invoice number gives invoice_number, accents dropped) while the key is empty or still follows the name, marked with a link icon; edit the key and it stays yours. Keys are checked as you type, paste, import and move fields: empty, wrong format, or already used by a sibling (or anywhere, with uniqueKeys="global"), ignoring case and outer spaces. Every field involved is marked, the toolbar counts the problems, and clicking the count, or Enter / Shift+Enter in a marked input, steps through them. Picking a field type adjusts the type (Date stores a string with format date, Multi-select an array of options) and the type list offers what fits first; options typed for a select survive a switch to text and back. Groups, lists of objects and options open under their row from a Configure schema bar, each level a table of its own; the checkbox in the Required header marks a whole level required. Drag the grip on a row's left edge (it shows on hover and focus, always on touch) to reorder or to move a field into or out of a group: a line shows where it lands, in amber when the key already exists there. On touch, long press the grip. From the keyboard, Alt+↑/↓ moves a field, Alt+←/→ (on the grip, selects and the checkbox) moves it out of or into a group, and the ⋯ menu does the same plus Duplicate, Edit details and Delete (a field with children asks first). ⌘Z / ⇧⌘Z (Ctrl+Z / Ctrl+Y) undo and redo inside the builder, Escape in an input puts back what it held. Edit details opens a side panel with the format, placeholder, default value and options. The JSON tab shows the draft 2020-12 schema, highlighted, with Show changes for a diff against the schema it opened with. Import JSON reads a pasted or chosen file and points at the line of an error. Below 560px rows become cards that open the editor in a bottom sheet; menus and selects become bottom sheets on phones.
Schema Builder is a Pro React component in the React form components category, written in TypeScript for React 19 and Tailwind CSS v4. It installs as source with npx wingo-ui@latest add schema-builder, together with Alert Dialog, Button, Checkbox, Code Block, Dialog and 16 more and the npm packages @dnd-kit/core, @dnd-kit/sortable, @dnd-kit/utilities, lucide-react and motion.
Add to a project
Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup
npx wingo-ui@latest add schema-builderSchema Builder is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans
Usage
Import SchemaBuilder from @/components/ui/schema-builder.
import { SchemaBuilder, serializeSchema, type SchemaBuilderField } from "@/components/ui/schema-builder"
const fields: SchemaBuilderField[] = [
{ id: "number", name: "Invoice number", key: "invoice_number", fieldType: "text", type: "string", required: true, description: "The invoice ID" },
{ id: "issued", name: "Issue date", key: "issue_date", fieldType: "date", type: "string", format: "date", required: true, description: "" },
]
export function InvoiceSchema() {
return (
<SchemaBuilder
defaultValue={fields}
height="80dvh"
onValueChange={(next) => console.log(serializeSchema(next).schema)}
onValidationChange={(errors) => console.log(errors.length, "problems")}
/>
)
}Props
defaultValuedefault"[]"SchemaBuilderField[]The fields it opens with while uncontrolled. The playground uses a Northwind Outfitters invoice. Show changes in the JSON tab compares against it.
valueSchemaBuilderField[]The fields, controlled. Pair it with onValueChange.
onValueChange(fields: SchemaBuilderField[]) => voidCalled with the new fields after every edit, move, import, undo and redo.
defaultTabdefault"form""form" | "json"The tab it opens on: the field table or the JSON Schema.
tab"form" | "json"The tab, controlled. Pair it with onTabChange.
onTabChange(tab: "form" | "json") => voidCalled when someone switches between Form and JSON.
uniqueKeysdefault"siblings""siblings" | "global"siblings: a key must be unique among the fields of its level (one group, one list). global: unique in the whole schema.
keyPatterndefault"^[a-z][a-z0-9_]*$"stringA regular expression every key must match. The default allows snake_case; the other options camelCase and kebab-case.
autoKeydefaulttruebooleanThe key follows the Name (its slug) while it is empty or unchanged; a link icon marks those keys. Off, keys are only typed by hand.
readOnlydefaultfalsebooleanShows the schema without editing: no grips, adds, imports or undo. Copy, download and the JSON tab stay.
maxDepthdefault5numberLevels of nesting allowed, 1 is flat. Deeper fields are reported; moves and drops that would go deeper are refused.
defaultExpandeddefaulttruebooleanGroups, lists and options open expanded. Off, only the top level shows; collapsed rows count the problems inside them.
showToolbardefaulttruebooleanThe toolbar with the Form / JSON tabs, the problem count, add, import, copy, download, undo and redo.
showImportdefaulttruebooleanImport JSON in the toolbar (the ⋯ menu when narrow) and in the empty state.
showDownloaddefaulttruebooleanThe download button, which saves the JSON Schema as fileName.
fileNamedefault"schema.json"stringName of the downloaded file, also shown in the download button's label.
heightdefault640number | stringHeight of the builder: px as a number, any CSS length ("80dvh") to fill a pane, or "auto" to grow with the fields.
variantdefault"surface""surface" | "outline" | "plain"surface is a raised panel, outline a bordered box, plain has no frame for panes that bring their own.
radiusdefault"md""none" | "sm" | "md" | "lg"Corner radius of the frame: 0, 12, 16 or 24px.
typeColorsPartial<Record<SchemaBuilderTypeKey, string>>Tints for the type badges, any CSS color per type (string, number, enum, array<object>...). Badges are neutral by default, like the rest of the library; set colors to tell types apart at a glance.
toolbarActionsReactNodeYour own buttons at the end of the toolbar, before the ⋯ menu: save, publish, test on a document.
refRef<SchemaBuilderHandle> (a useRef object or an (handle) => void callback)addField(parentId?), removeField(id), focusField(id, column?), validate() (shows every problem and returns them), getSchema(), getJsonSchema(), importJson(json), reset(), undo() and redo().
onJsonSchemaChange(schema: SchemaBuilderJsonSchema) => voidCalled with the serialized JSON Schema on open and after every change.
onValidationChange(errors: SchemaBuilderError[]) => voidCalled on open and whenever the problems change: { id, path, field, code, message, otherId? } for each.
onFieldAdd(field: SchemaBuilderField, parentId: string | null) => voidCalled when a field is added, duplicated or pasted in, with the group or list it went into (null for the top level).
onFieldRemove(field: SchemaBuilderField) => voidCalled with a deleted field, children included.
labelsPartial<SchemaBuilderLabels>Every string, English by default (DEFAULT_SCHEMA_BUILDER_LABELS): columns, field and JSON type names, menus, editor, import, JSON tab, announcements and every validation message, with functions for the ones that take a value (errorKeyDuplicate(otherName), problems(count)...).
classNamesPartial<Record<"toolbar" | "viewport" | "header" | "row" | "card" | "options" | "json" | "notice" | "editor" | "state", string>>Extra classes for the toolbar, the scrolling form, each level header, each row and card, the options editor, the JSON tab, the import notice, the editor panel and the empty state.
classNamestringExtra classes for the frame, merged last. Other div props are forwarded to it.
Parts
serializeSchema
functionserializeSchema(fields, options?) returns { schema, errors }: a draft 2020-12 JSON Schema (title from Name, description, format, enum with x-enum-descriptions, items, required on the parent, default, x-placeholder, x-field-type) and the problems. strict: true throws instead when there are any.
fields*SchemaBuilderField[]The fields to serialize. Fields without a key are left out; on a duplicate key the first one wins.
options{ strict?, uniqueKeys?, keyPattern?, maxDepth?, schemaUri?, title?, labels? }strict throws an error with the list on error.errors; schemaUri: false drops $schema.
parseSchema
functionparseSchema(json, options?) reads a JSON Schema, as text or an object, into fields and never throws: { fields, errors, warnings }. A JSON syntax error comes with its line and column; $ref, allOf and other unsupported parts are reported in warnings.
json*string | objectThe schema. Titles become names, formats pick the field type, oneOf / anyOf consts become options.
options{ idPrefix?: string; labels? }idPrefix keeps the generated ids stable and distinct between imports.
validateSchema
functionvalidateSchema(fields, options?) returns every problem in reading order: empty names and keys, key format, duplicate keys (case and outer spaces ignored), options, empty groups, a field type that cannot store the type, nesting past maxDepth.
fields*SchemaBuilderField[]The fields to check.
options{ uniqueKeys?: "siblings" | "global"; keyPattern?: string | RegExp; maxDepth?: number; labels? }The same rules the builder uses.
slugifyKey
functionslugifyKey(name) turns a name into a key: "Invoice number" gives invoice_number, "Preț unitar" gives pret_unitar, a leading digit gets field_.
typeKeyOf
functiontypeKeyOf(field) returns the type as one value: "string", "enum", or "array<object>" for an array of objects.
SchemaBuilderField
typeA field: { id, name, key, fieldType, type, required, description, enumValues?, properties?, items?, format?, placeholder?, defaultValue? }. properties holds an object's children, items what an array holds ({ type, properties?, enumValues? }).
SchemaBuilderEnumValue
typeAn option of a select, radio or multi-select field: { id, value, description? }.
SchemaBuilderFieldType
typetext, textarea, number, currency, percent, select, multi-select, radio, checkbox, switch, date, datetime, time, email, phone, url, file, signature, address, group or list.
SchemaBuilderType
typestring, number, integer, boolean, null, object, array or enum: the JSON type a field stores.
SchemaBuilderError
typeA problem: { id, path ("vendor.address.city", "line_items[].amount"), field ("name" | "key" | "type" | "enumValues" | "properties"), code, message, otherId? }.
SchemaBuilderJsonSchema
typeWhat serializeSchema, getJsonSchema() and onJsonSchemaChange give you: { $schema?, type: "object", properties, required? }.
SchemaBuilderHandle
typeWhat the ref gets: addField, removeField, focusField, validate, getSchema, getJsonSchema, importJson, reset, undo and redo.
SchemaBuilderLabels
typeThe shape of labels: every string the builder renders and every message it reports.
DEFAULT_SCHEMA_BUILDER_LABELS
constantThe English labels. Spread it to translate a few strings.
SchemaBuilderTypeKey
typeA type as one value: "string", "enum", "object", "array<object>", "array<enum>", "array<string>"...
DEFAULT_KEY_PATTERN
constant^[a-z][a-z0-9_]*$, the key pattern used when keyPattern is not set.
Examples
JSON and problems outside the builder
onJsonSchemaChange hands you the draft 2020-12 schema on every change, onValidationChange the list of problems with their paths.
Duplicate keys in the data
“total” and “total ” clash at the root, “amount” and “Amount” inside the line items: case and spaces are ignored, every field involved is marked.
Unique across the whole schema
uniqueKeys="global": the vendor's and the customer's "name" now clash too. Collapsed groups count the problems inside them.
Import an existing JSON Schema
A purchase order schema read with parseSchema: formats become Date and Email fields, oneOf consts become options. The second button shows the import error.
Empty schema
No fields yet: add the first one or import a JSON Schema.
Read-only
readOnly shows the schema without editing; the row menu keeps View details and Copy key, the toolbar keeps Copy JSON and Download.
Your own toolbar actions
toolbarActions adds Save, which calls validate() on the ref and reads getJsonSchema().
On a phone
Rows become cards with the name as title and a Required switch; tap one to edit it in a bottom sheet, long press the grip to drag.
Dependencies
Files
- components/ui/schema-builder.tsx
FAQ
Is the React Schema Builder component free?
The preview, props and docs are free; copying the source needs a Pro plan. See plans.
How do I install Schema Builder?
Run npx wingo-ui@latest add schema-builder. It also adds the Wingo UI items it builds on (Alert Dialog, Button, Checkbox, Code Block, Dialog and 16 more) and the npm packages @dnd-kit/core, @dnd-kit/sortable, @dnd-kit/utilities, lucide-react and motion. With shadcn, add the @wingo-ui registry with your API key, then run npx shadcn@latest add @wingo-ui/schema-builder.
How does Schema Builder behave on phones?
The Field type (the control a form shows: text, date, currency, select, address...) is set in Edit details and shown on phone cards. Below 560px rows become cards that open the editor in a bottom sheet; menus and selects become bottom sheets on phones.
See also
More React form components
New components by email
New posts, product news and occasional offers from Wingo UI. We count clicks to keep it relevant.