Skip to main content

Controls

Controls represent the basic building blocks for creating forms.

A control is usually displaying the value of one property from the data in an UI element such as an input field. How a control is rendered depends on the type of the property as defined in the JSON Schema, e.g. a property of type boolean is rendered as a Checkbox by default.

scope (string)#

The mandatory scope property, which expects a JSON schema reference value, defines to which property of the data the control should be bound to.

For instance, let's suppose we want to create a control for the name property in this schema:

{
"properties": {
"name": {
"type": "string"
}
}
}

The corresponding UI Schema needs to set the type of the UI Schema Element to Control and set the scope to point to the name property from the JSON schema as follows:

{
"type": "Control",
"scope": "#/properties/name"
}

JSON Forms will render the following form from this UI Schema:

JSON Forms ships with a default renderer set which consists of renderers for all primitive types as well as for arrays. Furthermore JSON Forms allows controls to be replaced or new controls to be added for newly invented UI Schema Elements. For documentation on these so called Custom Renderers please see the section about Custom Renderers.

label (string | boolean)#

By default, controls use the name of property they point to as a label. You can customize this behaviour by specifying a label property:

{
"type": "Control",
"scope": "#/properties/name",
"label": "First name"
}

Here's the rendered form:

You can also completely disable the label by setting it to false.

Options#

Controls can have an optional attribute options specifying how the control shall be rendered. Among the default renderers that support customization via the options attribute are the array and enum renderers.

The detail option#

When using the detail option, the items in the array will have a detail view. The detail element can have one of the values:

DEFAULT

options: {
detail : 'DEFAULT'
}

The array will be rendered as before. The string is case insensitive.

GENERATED

options: {
detail : 'GENERATED'
}

The array will be rendered using the nested array renderer. The nested renderer will use a generated UI Schema to render the array elements. The string is case insensitive.

REGISTERED

options: {
detail : 'REGISTERED'
}

The array will be rendered using the nested array renderer. The nested renderer will check if a UI Schema was registered for the type to be rendered or generate one itself. This case will be triggered if detail is any string besides GENERATED (case insensitive) or DEFAULT (case insensitive).

Inlined UI schema

options: {
detail : {
type: 'HorizontalLayout',
...
}
}

The array will be rendered using the nested array renderer. The nested renderer will use the specified UI Schema to render the array elements.

Sorting buttons (showSortButtons)#

options: {
showSortButtons: true
}

The showSortButtons option is used to toggle additional buttons that allow changing the order of elements within an array.

Label for array elements (elementLabelProp)#

options: {
elementLabelProp: "propertyName"
}

The elementLabelProp option allows to set a property to serve as a label for each array item. This option can be provided as a string or an array. More information can be found here: https://lodash.com/docs/4.17.15#get

By default the first primitive (string, number, integer) element will be used.

In the following example each element will be labeled with its name instead of its message because we provide the name prop.

Radio groups (format: 'radio')#

options: {
format: 'radio'
}

Use the format: 'radio' option to display an enum as a radio group.

The readonly option#

options: {
readonly: true
}

When using the readonly option, you can disable the control or whole layout. See example.

Theming#

Customize 'clear input button' background#

const customizedTheme = createMuiTheme({
jsonforms: { input: { delete: { background: '#f44336' }}}
});
<ThemeProvider theme={customizedTheme}>
<JsonForms
...
/>
</ThemeProvider>

The background of the the 'clear input button' (the one you can see when you hover of the input field) is by default your theme's palette.background.default color. If you want to customize the background of this button you can use the custom theme variable jsonforms.input.delete.background.