JSON Form
A form generated from a JSON Schema, laid out by the schema, a UI schema or your own markup.
c2-json-form
A form generated from a JSON Schema. The schema describes the data and how it is validated; how the form looks is decided in three layers, each optional:
- Nothing: one field per property, in schema order, each control picked from the property's
type,formatandenum(text field, number input, checkbox, select or radio group, date input, tag input…). Objects become groups, arrays of objects repeatable groups. ui-schema: a layout tree in the JSON Forms shape.VerticalLayout,HorizontalLayout,GridLayout(options.columns, default 2; a child takes one column unless it setsoptions.span),Group(options.collapsible),Categorization(tabs, oroptions.variant: "stepper") andLabelholdControls, each pointing at the data with ascope(#/properties/name). Aruleshows, hides, enables or disables any element from the data;options.widgetpicks another control.{ "type": "Control", "scope": "*" }stands for every field not placed elsewhere.- Markup: put
c2-json-fieldelements (with any HTML around them) inside the form and they replace the generated layout, each rendering the field itsscopenames.
A new kind of control or layout is a renderer: registerRenderer({ name, tester, render }) for every form, or the
form's renderers property for one. The highest tester rank wins.
Validation runs on every change with the built-in validator (or validator). A field shows its error once it is
committed (change), or for every field after reportValidity() or a submit attempt. Errors of fields a rule hides
are ignored. Inside a <form>, the element is a form control: it submits its value as JSON under name, blocks
submit while invalid and resets with the form.
The value is a plain object. An emptied text field removes its key, so required reports it.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
schema | JsonSchema | {} | The JSON Schema of the value. A JSON string is parsed. |
ui-schema | UiElement | undefined | undefined | The layout: a UI schema element tree. Without it, one field per property in schema order. A JSON string is parsed. |
name | string | — | Submitted as JSON under this name by an enclosing <form>. |
disabled | boolean | false | Disables every control; the value is not submitted and does not block a form while disabled. |
readonly | boolean | false | Every control is read-only. |
value | unknown | — | The data the form edits. Defaults from the schema are filled in where the value has none. |
Slots
| Name | Description |
|---|---|
(default) | c2-json-field elements and any markup around them. When present, they replace the generated layout. |
Events
| Name | Type | Description |
|---|---|---|
input | Event | Fired on every edit, after value is updated. |
change | Event | Fired when an edit is committed (a text field loses focus, a checkbox toggles, an item is added). |
CSS parts
Shadow DOM styling hooks used with ::part(name). Prefer CSS custom properties when they cover the change.
| Name | Description |
|---|---|
field | Every c2-form-field; field-<key> names one by its property, e.g. ::part(field-email). |
group | An object, a list or a Group (group-<key> for a property). |
group-label | A group's heading. |
group-error | An error about a whole group or list. |
layout | A vertical, horizontal or grid layout. |
label | A Label element. |
categorization | The tabs or the stepper of a Categorization. |
stepper-actions | The Back and Next buttons of a stepper. |
array-item | One item of a list. Every element also carries the names in its options.part. |
array-item-header | The row above a list item holding its number and its Remove button. |
array-actions | The row holding the Add button. |
CSS custom properties
Grouped by semantic target and state from --c2-<component>__<target>__<state>--<property>. Click a group to collapse it; click a name to copy it.
| Name | Type | Default | Description |
|---|---|---|---|
--c2-json-form--gap | pixel | 16px | Space between the elements of a layout. |
--c2-json-form__horizontal__item--min-width | pixel | 200px | A horizontal layout wraps a child narrower than this onto the next row. |
--c2-json-form__grid--column-gap | pixel | 16px | |
--c2-json-form__grid--row-gap | pixel | 16px | |
--c2-json-form__grid--preferred-width | pixel | 480px | The width a grid asks for when the form is sized to its content; narrower than 480px, it stacks into one column. |
--c2-json-form__label--color | color | #71717a | Text of a Label element. |
--c2-json-form__label--font-size | font-size | 14px | |
--c2-json-form__group-label--color | color | #18181b | |
--c2-json-form__group-label--font-size | font-size | 14px | |
--c2-json-form__group-label--font-weight | font-weight | 600 | |
--c2-json-form__group-error--color | color | #dc2626 | An error about a whole group or list, such as minItems. |
--c2-json-form__group-error--font-size | font-size | 12px | |
--c2-json-form__array-item--border-bottom | border | 1px solid #e4e4e7 | Separates the items of a list. |
--c2-json-form__array-item--padding-bottom | pixel | 16px | |
--c2-json-form__array-item-header--color | color | #71717a | |
--c2-json-form__array-item-header--font-size | font-size | 12px | |
--c2-json-form__step-label--font-family | font-family | system-ui, sans-serif | The stepper's step names. |
--c2-json-form__slider--margin-top | pixel | 24px | Room above a slider for the value it shows over its thumb. |
Text and languages
The text the component shows, in English. It shows another language when the app adds one with addTranslations, under json-form, and the nearest lang asks for it; any message not translated stays in English. {0}, {1}… stand for the values a message carries. Languages guide.
| Key | English | Values |
|---|---|---|
required | Fill in this field. | — |
requiredChoice | Select an option. | — |
invalid | Enter a valid value. | — |
formatEmail | Enter an email address, like name@example.com. | — |
formatUri | Enter a web address, like https://example.com. | — |
formatDate | Enter a date. | — |
formatTime | Enter a time. | — |
pattern | Use the requested format. | — |
enum | Select one of the options. | — |
minLength | Use at least {0} characters. | {0} limit |
maxLength | Use {0} characters or fewer. | {0} limit |
minimum | Enter {0} or more. | {0} limit |
maximum | Enter {0} or less. | {0} limit |
exclusiveMinimum | Enter more than {0}. | {0} limit |
exclusiveMaximum | Enter less than {0}. | {0} limit |
multipleOf | Enter a multiple of {0}. | {0} limit |
minItems | Add at least {0} items. | {0} limit |
maxItems | Add no more than {0} items. | {0} limit |
uniqueItems | Remove the duplicate items. | — |
selectPlaceholder | Select… | — |
addItem | Add | — |
removeItem | Remove | — |
item | Item {0} | {0} position |
previous | Back | — |
next | Next | — |
c2-json-field
Places one field of the enclosing c2-json-form in your own markup. Put these, with any HTML and CSS around them,
inside the form and they replace its generated layout: the form still owns the value, validation and events, and
each field renders the control (with its label, hint and error) for the data its scope names.
scope="*" renders every field that no other c2-json-field of the form places, so a field added to the schema
still shows up. A scope naming an object renders the object's group.
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
scope | string | — | The data this field edits: #/properties/billing/properties/zip, the shorthand billing.zip, or * for the rest. |
label | string | undefined | undefined | Replaces the schema's title. |
options | UiOptions | undefined | undefined | The control's UI schema options, e.g. {"widget": "textarea"}. A JSON string is parsed. |