uiSchema
JSON Schema is limited for describing how a given data type should be rendered as a form input component. That's why this library introduces the concept of uiSchema.
A UI schema is basically an object literal providing information on how the form should be rendered, while the JSON schema tells what.
The uiSchema object follows the tree structure of the form field hierarchy, and defines how each property should be rendered.
Note that almost every property within uiSchema can be rendered in one of two ways: {"ui:options": {[property]: [value]}}, or {"ui:[property]": value}.
In other words, the following uiSchemas are equivalent:
{
"ui:title": "Title",
"ui:description": "Description",
"ui:classNames": "my-class",
"ui:submitButtonOptions": {
"props": {
"disabled": false,
"className": "btn btn-info"
},
"norender": false,
"submitText": "Submit"
}
}
{
"ui:options": {
"title": "Title",
"description": "Description",
"classNames": "my-class",
"submitButtonOptions": {
"props": {
"disabled": false,
"className": "btn btn-info"
},
"norender": false,
"submitText": "Submit"
}
}
}
For a full list of what is supported in the uiSchema see the UiSchema type in @rjsf/utils/types.ts.
Be sure to pay attention to the hierarchical intersection to these other types: UIOptionsBaseType and TemplatesType.
Exceptions to the equivalence
There are 4 properties that exist in a UiSchema that will not be found in an inner ui:options object.
ui:globalOptions
The set of globally relevant UiSchema options that are read from the root-level UiSchema and stored in the registry for use everywhere.
import { UiSchema } from '@rjsf/utils';
const uiSchema: UiSchema = {
'ui:globalOptions': { copyable: true },
};
ui:rootFieldId (deprecated)
DEPRECATED: Use
Form.idPrefixinstead, will be removed in a future major version
By default, this library will generate ids unique to the form for all rendered widgets.
If you plan on using multiple instances of the Form component in a same page, it's wise to declare a root prefix for these, using the ui:rootFieldId uiSchema directive:
import { UiSchema } from '@rjsf/utils';
const uiSchema: UiSchema = {
'ui:rootFieldId': 'myform',
};
This will make all widgets have an id prefixed with myform.
ui:field
The ui:field property overrides the Field implementation used for rendering any field in the form's hierarchy.
Specify either the name of a field that is used to look up an implementation from the fields list or an actual one-off Field component implementation itself.
See Custom Widgets and Fields for more information about how to use this property.
ui:fieldReplacesAnyOrOneOf
By default, any field that is rendered for an anyOf/oneOf schema will be wrapped inside the AnyOfField or OneOfField component.
This default behavior may be undesirable if your custom field already handles behavior related to choosing one or more subschemas contained in the anyOf/oneOf schema.
By providing a true value for this flag in association with a custom ui:field, the wrapped components will be omitted, so just one instance of the custom field will be rendered.
If the flag is omitted or set to false, your custom field will be wrapped by AnyOfField/OneOfField.
ui:options
The ui:options property cannot be nested inside itself and thus is the last exception.
ui:XXX or ui:options.XXX
All the properties that follow can be specified in the uiSchema in either of the two equivalent ways.
NOTE: The properties specific to array items can be found here. For advanced dynamic UI schema capabilities for array items, see the Dynamic UI Schema Examples.
widget
The ui:widget property overrides the Widget implementation used for rendering any field in the form's hierarchy.
Specify either the name of a widget that is used to look up an implementation from the widgets list or an actual one-off Widget component implementation itself.
See Custom Widgets and Fields for more information about how to use this property.
classNames
The uiSchema object accepts a ui:classNames property for each field of the schema:
import { UiSchema } from '@rjsf/utils';
const uiSchema = {
title: {
'ui:classNames': 'task-title foo-bar',
},
};
Will result in:
<div class="field field-string task-title foo-bar">
<label>
<span>Title*</span>
<input value="My task" required="" type="text" />
</label>
</div>
style
The uiSchema object accepts a ui:style property for each field of the schema:
import { UiSchema } from '@rjsf/utils';
const uiSchema = {
title: {
'ui:style': { color: 'red' },
},
};
Will result in:
<div class="field field-string task-title" style={{ color: "red" }}>
<label>
<span>Title*</span>
<input value="My task" required="" type="text">
</label>
</div>