react-jsonschema-form Documentation

Packages Docs Package.Json (`packages/docs/package.json`) Copy Section

{
"name": "@rjsf/docs",
"version": "6.11.0",
"private": true,
"scripts": {
"docusaurus": "docusaurus",
"start": "docusaurus start",
"build": "docusaurus build",
"swizzle": "docusaurus swizzle",
"deploy": "docusaurus deploy",
"clear": "docusaurus clear",
"serve": "docusaurus serve",
"write-translations": "docusaurus write-translations",
"write-heading-ids": "docusaurus write-heading-ids",
"typecheck": "tsc",
"precommit": "lint-staged",
"cs-check": "oxfmt --check "src//*.{ts,tsx}"",
"cs-format": "oxfmt "src//.{ts,tsx}""
},
"lint-staged": {
"src/**/.{ts,tsx}": [
"oxfmt"
]
},
"dependencies": {
"@docusaurus/core": "^3.10.2",
"@docusaurus/preset-classic": "^3.10.2",
"@mdx-js/react": "^3.1.1",
"prism-react-renderer": "^2.4.1"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "^3.10.2",
"@docusaurus/plugin-content-docs": "^3.10.2",
"@docusaurus/types": "^3.10.2",
"@tsconfig/docusaurus": "^2.0.9"
},
"browserslist": {
"production": [
">0.5%",
"not dead",
"not op_mini all"
],
"development": [
"last 1 chrome version",
"last 1 firefox version",
"last 1 safari version"
]
},
"engines": {
"node": ">=20"
}
}

Packages Docs Tsconfig.Json (`packages/docs/tsconfig.json`) Copy Section

{
// This file is not used in compilation. It is here just for a nice editor experience.
"extends": "@tsconfig/docusaurus/tsconfig.json",
"compilerOptions": {
"resolveJsonModule": true
}
}

Packages Docs Docs 00 Introduction (`packages/docs/docs/00-introduction.mdx`) Copy Section

id: intro title: Introduction slug: / Copy Chapter

react-jsonschema-form

A simple React component capable of building HTML forms out of a JSON schema.

A live playground is hosted on GitHub Pages:

Philosophy Copy Chapter

react-jsonschema-form is meant to automatically generate a React form based on a JSON Schema. If you want to generate a form for any data, sight unseen, simply given a JSON schema, react-jsonschema-form may be for you. If you have a priori knowledge of your data and want a toolkit for generating forms for it, you might look elsewhere.

react-jsonschema-form also comes with tools such as uiSchema and other form props to customize the look and feel of the form beyond the default themes.

Installation Copy Chapter

First install the dependencies from npm, along with a validator implementation (such as @rjsf/validator-ajv8):

$ npm install @rjsf/core @rjsf/utils @rjsf/validator-ajv8 --save

Then import the dependencies as follows:

import Form from '@rjsf/core';
import validator from '@rjsf/validator-ajv8';

Our latest version requires React 16+.

Usage Copy Chapter

import Form from '@rjsf/core';
import { RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  title: 'Todo',
  type: 'object',
  required: ['title'],
  properties: {
    title: { type: 'string', title: 'Title', default: 'A new task' },
    done: { type: 'boolean', title: 'Done?', default: false },
  },
};

const log = (type) => console.log.bind(console, type);

render(
  <Form
    schema={schema}
    validator={validator}
    onChange={log('changed')}
    onSubmit={log('submitted')}
    onError={log('errors')}
  />,
  document.getElementById('app')
);

Theming Copy Chapter

For more information on what themes we support, see Using Themes.

License Copy Chapter

Apache 2

Credits Copy Chapter

Who uses react-jsonschema-form? Copy Chapter

• ...

Add your own company / organization by making a pull request.

Packages Docs Docs Contributing (`packages/docs/docs/contributing.md`) Copy Section

Contributing

Development server Copy Chapter

We are using Vite to power our playground, which caches all the built @rjsf/* distributions.
In order to test the playground locally after a new clone or fresh pull from main, run the following from the root directory of the monorepo:

pnpm install
pnpm run build
cd packages/playground
pnpm start

This will start the live development server showcasing components at localhost:8080.

Whenever you make changes to source code, stop the running playground and return to the root directory and rerun pnpm run build.
Thanks to nx caching, this should only rebuild what is necessary.
After the build is complete, return to the root of the playground and restart the server via pnpm start.

First time step Copy Section

If this is the first time you have cloned the repo, run the pnpm run prepare script that will set up husky to provide a git precommit hook that will format and lint any code you have added to a PR.

Optional development process Copy Section

With the large number of packages, sometimes running pnpm run build or pnpm start from the root directory will overwhelm an underpowered computer.
If that is the situation for you, you can instead use pnpm run build-serial to build the packages one at a time instead of all at once.
Also, if you are only working on one package, you can pnpm run build and pnpm run test from within the subdirectory.
Finally, you can simply pnpm start inside of the playground directory to test changes if you have already built all of your packages, without needing to watch all of the packages via the root directory pnpm start.

Troubleshooting build failures Copy Section

Sometimes your local builds fail and you can't figure out why. This is most likely to happen after rebase to main due
to package.json changes upstream. There are two commands you can use to (hopefully) get your environment back to a
working state. Try running the following two commands:

pnpm run refresh-node-modules
pnpm run clean-build

The first command will delete all of the node_modules directories in the environment and then rerun pnpm install.
The second command cleans up the typescript build cache files before retrying the build.

Worst case scenario when neither of those commands work, try running pnpm run nuke-build-env and then rerun the two commands.

Cloud builds Copy Chapter

When building in environments with limited memory, such as Netlify, it's recommended to use pnpm run build-serial that builds the packages serially.

Coding style Copy Chapter

All the JavaScript/Typescript code in this project conforms to the prettier coding style.
Code is automatically prettified upon commit using precommit hooks, assuming you followed the First time step above.

You can also run pnpm cs-format within any package directory you are changing.

Documentation Copy Chapter

We use Docusaurus to build our documentation. To run documentation locally, run:

cd packages/docs
pnpm start

Documentation will be served on localhost:3000.

Tests Copy Chapter

You can run all tests from the root directory OR from packages subdirectory using the following command:

pnpm run test

Snapshot testing Copy Section

All the themes, including core use snapshot testing (NOTE: core also has extensive non-snapshot tests).
The source-code of these snapshot tests reside in the core package in the testSnap directory and are shared with all the themes.
In order to support the various themes, the code for the tests are actually functions that take two parameters:

• Form: ComponentType<FormProps> - The component from the theme implementation
• [customOptions]: { [key: string]: TestRendererOptions } - an optional map of react-test-renderer TestRendererOptions implementations that some themes need to be able properly run

There are functions in the testSnap directory: arrayTests, formTests and objectTests, each with its own definition of customOptions

Each theme will basically run these functions by creating a Xxx.test.tsx file (where Xxx is Array, Form or Object) that looks like the following:

import { arrayTests } from '@rjsf/snapshot-tests'; // OR
// import { formTests } from '@rjsf/snapshot-tests';
// import { objectTests } from '@rjsf/snapshot-tests';

import Form from '../src';

arrayTests(Form); // OR
// formTests(Form);
// objectTests(Form);

Anytime you add a new feature, be sure to update the appropriate xxxTests() function in the testSnap directory and do pnpm run test from the root directory to update all the snapshots.
If you add a theme-only feature, it is ok to update the appropriate Xxx.test.tsx file to add (or update) the theme-specific describe() block.
For example:

import { RJSFSchema, UiSchema } from '@rjsf/utils';
import { arrayTests } from '@rjsf/snapshot-tests';

import Form from '../src';

formTests(Form);

describe('Theme specific tests', () => {
  it('test a theme-specific option', () => {
    const schema: RJSFSchema = {
      type: 'object',
      properties: {
        name: {
          type: 'string',
        },
      },
    };
    const uiSchema: UiSchema = {
      // Enable the theme specific feature
    };
    const tree = renderer.create(<Form schema={schema} uiSchema={uiSchema} validator={validator} />).toJSON();
    expect(tree).toMatchSnapshot();
  });
});

See the antd Form.test.tsx for a specific example of this.

Code coverage Copy Section

Code coverage reports are currently available only for the @rjsf/core theme package.
They are generated using nyc each time the pnpm test-coverage script is run.
The full report can be seen by opening ./coverage/lcov-report/index.html.

Utils and validator-ajv8 code coverage

100% code coverage is required by the @rjsf/utils and @rjsf/validator-ajv8 tests.
If you make changes to those libraries, you will have to maintain that coverage, otherwise the tests will fail.

NOTE: All three of these directories share the same tests for verifying validator based APIs. See the documentation in the getTestValidator() functions for more information.

Releasing Copy Chapter

To release, go to the main branch (NOT a fork) and then create a new branch with the version number (with an rc prefix instead of v).
For instance if you are about to create the new 6.100.10 branch, then you would run the following commands:

git checkout -b rc6.100.10
pnpm exec nx release version --git-tag
git commit -m "Releasing 6.100.10"
git push
pnpm run update-version-tags

Make sure you use semver for version numbering when selecting the version.
The pnpm exec nx release version --git-tag command will update the package*.json files and create a new version tag.
Committing and pushing the branch will allow you to create the PR on GitHub.
The pnpm run update-version-tags will push the tags up to GitHub.

Then, make a PR to main. Merge the PR into main -- make sure you use "merge commit", not squash and merge, so that
the original commit where the tag was based on is still present in the main branch.

Then, create a release in the GitHub "Releases" tab, select the new tag that you have added,
and add a description of the changes in the new release. You can copy
the latest changelog entry in CHANGELOG.md to make the release notes, and update as necessary.

This will trigger a GitHub Actions pipeline that will build and publish all packages to npm.

The package is published through an automation token belonging to the
rjsf-bot user on npm. This token
is stored as the NPM_TOKEN secret on GitHub Actions.

Releasing docs Copy Section

Docs are automatically published to GitHub Pages when the main branch is updated.

We are currently in the process of automatically configuring versionable documentation on our new docs site.

Releasing the playground Copy Section

The playground automatically gets deployed from GitHub Pages.

If you need to manually publish the latest playground to https://rjsf-team.github.io/react-jsonschema-form/, though, run:

cd packages/playground
pnpm run publish-to-gh-pages

Releasing a new package Copy Section

Publishing a new @rjsf/* package requires additional setup. The package must first be published locally, then in the NPM web app, you must set up "Trusted Publishing" so future releases can be published via GitHub Actions. The steps to accomplish this are:

1. Create the new release as described above. Existing packages will be published, but the jobs to publish new package(s) will fail.
2. Locally, check out the release tag (e.g. git checkout v6.8.0). You may need to git fetch --tags. Make sure your git status is clean.
3. cd packages/new-package
4. pnpm login (login to an account with RJSF publishing privileges)
5. pnpm publish --no-git-checks.

The new package will be released. Then, set up Trusted Publishing:

1. Navigate to the new package in NPM (e.g. https://www.npmjs.com/package/@rjsf/new-package)
2. Go to Settings -> Trusted Publisher -> GitHub Actions
3. Set up the fields to match an existing package (e.g. look at @rjsf/core).
   1. Organization or user: rjsf-team
   2. Repository: react-jsonschema-form
   3. Workflow filename: release.yml
   4. Allow npm publish

Packages Docs Versioned Sidebars Version 3.2.1 Sidebars.Json (`packages/docs/versioned_sidebars/version-3.2.1-sidebars.json`) Copy Section

{
"docs": [
{
"type": "autogenerated",
"dirName": "."
}
]
}

Packages Docs Versioned Sidebars Version 4.2.3 Sidebars.Json (`packages/docs/versioned_sidebars/version-4.2.3-sidebars.json`) Copy Section

{
"docs": [
{
"type": "autogenerated",
"dirName": "."
}
]
}

Packages Docs Versioned Sidebars Version 5.24.10 Sidebars.Json (`packages/docs/versioned_sidebars/version-5.24.10-sidebars.json`) Copy Section

{
"docs": [
{
"type": "autogenerated",
"dirName": "."
}
]
}

Packages Docs Docs Advanced Customization Custom Templates (`packages/docs/docs/advanced-customization/custom-templates.md`) Copy Section

Custom Templates

This is an advanced feature that lets you customize even more aspects of the form:

In version 5, all existing templates were consolidated into a new TemplatesType interface that is provided as part of the Registry.
They can also be overloaded globally on the Form via the templates prop as well as globally or per-field through the uiSchema.
Further, many new templates were added or repurposed from existing widgets and fields in an effort to simplify the effort needed by theme authors to build new and/or maintain current themes.
These new templates can also be overridden by individual users to customize the specific needs of their application.
A special category of templates, ButtonTemplates, were also added to support the easy replacement of the Submit button on the form, the Add and Remove buttons associated with additionalProperties and patternProperties on objects and elements of arrays, as well as the Move up and Move down buttons used for reordering arrays.
This category, unlike the others, can only be overridden globally via the templates prop on Form.

Below is the table that lists all the templates, their props interface, their uiSchema name and from where they originated in the previous version of RJSF:

ArrayFieldTemplate Copy Chapter

You can use an ArrayFieldTemplate to customize how your arrays are rendered.
This allows you to customize your array, and each element in the array.
If you only want to customize how the array's title, description or how the array items are presented, you may want to consider providing your own ArrayFieldDescriptionTemplate, ArrayFieldItemTemplate and/or ArrayFieldTitleTemplate instead.
You can also customize arrays by specifying a widget in the relevant ui:widget schema, more details over on Custom Widgets.

import { ArrayFieldTemplateProps, RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'array',
  items: {
    type: 'string',
  },
};

function ArrayFieldTemplate(props: ArrayFieldTemplateProps) {
  return (
    <div>
      {props.items.map((element) => element.children)}
      {props.canAdd && <button type='button' onClick={props.onAddClick}></button>}
    </div>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ ArrayFieldTemplate }} />,
  document.getElementById('app'),
);

You also can provide your own field template to a uiSchema by specifying a ui:ArrayFieldTemplate property with your Component :

import { UiSchema } from '@rjsf/utils';
import ArrayFieldTemplate from './ArrayFieldTemplate';

const uiSchema: UiSchema = {
  'ui:ArrayFieldTemplate': ArrayFieldTemplate,
};

or a string value from the Registry :

import { UiSchema } from '@rjsf/utils';

const uiSchema: UiSchema = {
  'ui:ArrayFieldTemplate': 'CustomArrayFieldTemplate',
};

Please see the customArray.tsx sample from the playground for another example.

The following props are passed to each ArrayFieldTemplate:

• canAdd: A boolean value stating whether new elements can be added to the array.
• className: The className string.
• disabled: A boolean value stating if the array is disabled.
• fieldPathId: An object containing the id for this object & ids for its properties.
• items: An array of React nodes representing the items in the array.
• onAddClick: (event?) => void: A function that adds a new item to the end of the array.
• readonly: A boolean value stating if the array is read-only.
• required: A boolean value stating if the array is required.
• hideError: A boolean value stating if the field is hiding its errors.
• schema: The schema object for this array.
• uiSchema: The uiSchema object for this array field.
• title: A string value containing the title for the array.
• formData: The formData for this array.
• errorSchema: The optional validation errors for the array field and the items within it, in the form of an ErrorSchema
• rawErrors: An array of strings listing all generated error messages from encountered errors for this widget
• registry: The registry object.

Note: Array and object field templates are always rendered inside the FieldTemplate. To fully customize an array field template, you may need to specify both ui:FieldTemplate and ui:ArrayFieldTemplate.

ArrayFieldDescriptionTemplate Copy Chapter

The out-of-the-box version of this template will render the DescriptionFieldTemplate with a generated id, if there is a description otherwise nothing is rendered.
If you want different behavior for the rendering of the description of an array field, you can customize this template.
If you want a different behavior for the rendering of ALL descriptions in the Form, see DescriptionFieldTemplate

import { ArrayFieldDescriptionProps, RJSFSchema, descriptionId } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'array',
  items: {
    type: 'string',
  },
};

function ArrayFieldDescriptionTemplate(props: ArrayFieldDescriptionProps) {
  const { description, fieldPathId } = props;
  const id = descriptionId(fieldPathId);
  return (
    <details id={id}>
      <summary>Description</summary>
      {description}
    </details>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ ArrayFieldDescriptionTemplate }} />,
  document.getElementById('app'),
);

You also can provide your own field template to a uiSchema by specifying a ui:ArrayFieldDescriptionTemplate property with your Component :

import { UiSchema } from '@rjsf/utils';
import ArrayFieldDescriptionTemplate from './ArrayFieldDescriptionTemplate';

const uiSchema: UiSchema = {
  'ui:ArrayFieldDescriptionTemplate': ArrayFieldDescriptionTemplate,
};

or a string value from the Registry :

import { UiSchema } from '@rjsf/utils';

const uiSchema: UiSchema = {
  'ui:ArrayFieldDescriptionTemplate': 'CustomArrayFieldDescriptionTemplate',
};

The following props are passed to each ArrayFieldDescriptionTemplate:

• description: The description of the array field being rendered.
• fieldPathId: The FieldPathId of the field in the hierarchy
• schema: The schema object for this array field.
• uiSchema: The uiSchema object for this array field.
• registry: The registry object.

ArrayFieldItemTemplate Copy Chapter

The ArrayFieldItemTemplate is used to render the representation of a single item in an array.
All of the ArrayFieldTemplate implementations in all themes get this template from the registry in order to render array fields items.
Each theme has an implementation of the ArrayFieldItemTemplate to render an array field item in a manner best suited to the theme.
If you want to change how an array field item is rendered you can customize this template (for instance to remove the buttons rendered by ArrayFieldItemButtonsTemplate).

import { ArrayFieldItemTemplateProps, RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'array',
  items: {
    type: 'string',
  },
};

function ArrayFieldItemTemplate(props: ArrayFieldItemTemplateProps) {
  const { children, className } = props;
  return <div className={className}>{children}</div>;
}

render(
  <Form schema={schema} validator={validator} templates={{ ArrayFieldItemTemplate }} />,
  document.getElementById('app'),
);

The following props are passed to each ArrayFieldItemTemplate:

• children: The html for the item's content.
• buttonsProps: The props to pass to the ArrayFieldItemButtonTemplate.
• className: The className string.
• disabled: A boolean value stating if the array item is disabled.
• hasToolbar: A boolean value stating whether the array item has a toolbar.
• index: A number stating the index the array item occurs in items.
• totalItems: A number stating the total number items in the array.
• itemKey: A stable, unique key for the array item.
• readonly: A boolean value stating if the array item is read-only.
• schema: The schema object for this array item.
• uiSchema: The uiSchema object for this array item.
• registry: The registry object.
• parentUiSchema: The UI schema of the array item's parent array field, used for customization in some themes

ArrayFieldItemButtonTemplate Copy Chapter

The ArrayFieldItemButtonTemplate is used to render the representation of the buttons used for copying, moving and deleting an item in an array.
All of the ArrayFieldItemTemplate implementations in all themes get this template from the registry in order to render array fields items' buttons.
Currently, only the core them has an implementation of this template as the button rendering is identical across all themes.
If you want to change how an array field item's buttons are rendered you can customize this template (for instance to remove the move up/down and remove buttons).

import { useMemo } from 'react';
import { ArrayFieldTemplateItemButtonsType, buttonId, RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'array',
  items: {
    type: 'string',
  },
};

function ArrayFieldItemButtonsTemplate(props: ArrayFieldTemplateItemButtonsType) {
  const { disabled, readonly, hasCopy, fieldPathId, index, onCopyIndexClick, registry, uiSchema } = props;
  const { CopyButton } = registry.templates.ButtonTemplates;
  const onCopyClick = useMemo(() => onCopyIndexClick(index), [index, onCopyIndexClick]);
  if (!hasCopy) {
    return undefined;
  }
  return (
    <CopyButton
      id={buttonId(fieldPathId, 'copy')}
      className='array-item-copy'
      disabled={disabled || readonly}
      onClick={onCopyClick}
      uiSchema={uiSchema}
      registry={registry}
    />
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ ArrayFieldItemButtonsTemplate }} />,
  document.getElementById('app'),
);

The following props are passed to each ArrayFieldItemButtonsTemplate:

• className: The className string.
• disabled: A boolean value stating if the array item is disabled.
• canAdd: A boolean value stating whether new elements can be added to the array.
• hasCopy: A boolean value stating whether the array item can be copied.
• hasMoveDown: A boolean value stating whether the array item can be moved down.
• hasMoveUp: A boolean value stating whether the array item can be moved up.
• hasRemove: A boolean value stating whether the array item can be removed.
• fieldPathId: The FieldPathId of the field in the hierarchy.
• index: A number stating the index the array item occurs in items.
• totalItems: A number stating the total number items in the array.
• onAddItem: event?) => void: Callback function that adds a new item below this item.
• onCopyItem: (event?) => void: Callback function that copies this item below itself.
• onRemoveItem: (event?) => void: Callback function that removes the item from the list.
• onMoveUpItem: (event?) => void: Callback function that moves the item up one spot in the list
• onMoveDownItem: (event?) => void: Callback function that moves the item down one spot in the list
• readonly: A boolean value stating if the array item is read-only.
• schema: The schema object for this array item.
• style: The optional style to pass to all of the buttons
• uiSchema: The uiSchema object for this array item.
• registry: The registry object.

ArrayFieldTitleTemplate Copy Chapter

The out-of-the-box version of this template will render the TitleFieldTemplate with a generated id, if there is a title otherwise nothing is rendered.
If you want a different behavior for the rendering of the title of an array field, you can customize this template.
If you want a different behavior for the rendering of ALL titles in the Form, see TitleFieldTemplate

import { ArrayFieldTitleTemplateProps, RJSFSchema, titleId } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'array',
  items: {
    type: 'string',
  },
};

function ArrayFieldTitleTemplate(props: ArrayFieldTitleProps) {
  const { title, fieldPathId } = props;
  const id = titleId(fieldPathId);
  return <h1 id={id}>{title}</h1>;
}

render(
  <Form schema={schema} validator={validator} templates={{ ArrayFieldTitleTemplate }} />,
  document.getElementById('app'),
);

You also can provide your own template to a uiSchema by specifying a ui:ArrayFieldDescriptionTemplate property with your Component :

import { UiSchema } from '@rjsf/utils';
import ArrayFieldDescriptionTemplate from './ArrayFieldDescriptionTemplate';

const uiSchema: UiSchema = {
  'ui:ArrayFieldDescriptionTemplate': ArrayFieldDescriptionTemplate,
};

or a string value from the Registry :

import { UiSchema } from '@rjsf/utils';

const uiSchema: UiSchema = {
  'ui:ArrayFieldDescriptionTemplate': 'CustomArrayFieldDescriptionTemplate',
};

The following props are passed to each ArrayFieldTitleTemplate:

• title: The title of the array field being rendered.
• fieldPathId: The FieldPathId of the field in the hierarchy.
• schema: The schema object for this array field.
• uiSchema: The uiSchema object for this array field.
• required: A boolean value stating if the field is required
• registry: The registry object.

BaseInputTemplate Copy Chapter

The BaseInputTemplate is the template to use to render the basic component for a theme. It is used as the template for rendering many of the based widgets that differ by type and callbacks only.
For example, the TextWidget implementation in core is simply a wrapper around BaseInputTemplate that it gets from the registry.
Additionally, each theme implements its own version of BaseInputTemplate without needing to provide a different implementation of TextWidget.

If you desire a different implementation for the `` based widgets, you can customize this template.
For instance, say you have a CustomTextInput component that you want to integrate:

/* Detailed source-code truncated for AI context efficiency. */

Wrapping BaseInputTemplate to customize it Copy Section

Sometimes you just need to pass some additional properties to the existing BaseInputTemplate.
The way to do this varies based upon whether you are using core or some other theme (such as mui):

import { BaseInputTemplateProps } from '@rjsf/utils';
import { getDefaultRegistry } from '@rjsf/core';
import { Templates } from '@rjsf/mui';

const {
  templates: { BaseInputTemplate },
} = getDefaultRegistry(); // To get templates from core
// const { BaseInputTemplate } = Templates; // To get templates from a theme do this

function MyBaseInputTemplate(props: BaseInputTemplateProps) {
  const customProps = {};
  // get your custom props from where you need to
  return <BaseInputTemplate {...props} {...customProps} />;
}

The following props are passed to the BaseInputTemplate:

• id: The generated id for this widget;
• schema: The JSONSchema subschema object for this widget;
• uiSchema: The uiSchema for this widget;
• value: The current value for this widget;
• placeholder: The placeholder for the widget, if any;
• required: The required status of this widget;
• disabled: A boolean value stating if the widget is disabled;
• hideError: A boolean value stating if the widget is hiding its errors.
• readonly: A boolean value stating if the widget is read-only;
• autofocus: A boolean value stating if the widget should autofocus;
• label: The computed label for this widget, as a string
• multiple: A boolean value stating if the widget can accept multiple values;
• onChange: The value change event handler; call it with the new value every time it changes;
• onChangeOverride: A BaseInputTemplate implements a default onChange handler that it passes to the HTML input component to handle the ChangeEvent. Sometimes a widget may need to handle the ChangeEvent using custom logic. If that is the case, that widget should provide its own handler via this prop;
• onKeyChange: The key change event handler (only called for fields with additionalProperties and patternProperties); pass the new value every time it changes;
• onBlur: The input blur event handler; call it with the widget id and value;
• onFocus: The input focus event handler; call it with the widget id and value;
• options: A map of options passed as a prop to the component (see Custom widget options).
• options.enumOptions: For enum fields, this property contains the list of options for the enum as an array of { label, value } objects. If the enum is defined using the oneOf/anyOf syntax, the entire schema object for each option is appended onto the { schema, label, value } object.
• rawErrors: An array of strings listing all generated error messages from encountered errors for this widget.
• registry: The registry object

CyclicSchemaExpandTemplate Copy Chapter

The CyclicSchemaExpandTemplate is the template rendered by CyclicSchemaField when a circular $ref cycle is detected in the schema.
RJSF automatically detects when a $ref would recurse indefinitely (e.g. a schema whose property references its own root) and stops rendering at the cycle boundary.
At that point CyclicSchemaField renders this template, which shows a warning message and an expand button that the user can click to render one additional level of the recursive structure.

Each theme provides its own implementation.
You can replace the template globally via the templates prop on Form, or per-field via ui:CyclicSchemaExpandTemplate in the uiSchema.

import { CyclicSchemaExpandProps, RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

// A schema that is self-referencing
const schema: RJSFSchema = {
  $schema: 'http://json-schema.org/draft-07/schema#',
  type: 'object',
  title: 'Node',
  properties: {
    value: { type: 'string' },
    child: { $ref: '#' },
  },
};

function CyclicSchemaExpandTemplate<T = any>(props: CyclicSchemaExpandProps<T>) {
  const { name, fieldPathId, onExpand } = props;
  const buttonId = `${fieldPathId.$id}-button`;
  return (
    <div className='cyclic-expand'>
      <span className='warning'>Circular reference detected for field &quot;{name}&quot;</span>
      <button id={buttonId} type='button' onClick={() => onExpand(fieldPathId.$id)}>
        Expand
      </button>
    </div>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ CyclicSchemaExpandTemplate }} />,
  document.getElementById('app'),
);

You can also provide a per-field template via uiSchema:

import { UiSchema } from '@rjsf/utils';
import CyclicSchemaExpandTemplate from './CyclicSchemaExpandTemplate';

const uiSchema: UiSchema = {
  'ui:CyclicSchemaExpandTemplate': CyclicSchemaExpandTemplate,
};

or a string value from the Registry:

import { UiSchema } from '@rjsf/utils';

const uiSchema: UiSchema = {
  'ui:CyclicSchemaExpandTemplate': 'CustomCyclicSchemaExpandTemplate',
};

The following props are passed to the CyclicSchemaExpandTemplate as defined by CyclicSchemaExpandProps in @rjsf/utils:

• name: The unique name of the field at the cycle boundary, usually the property name within its parent object.
• fieldPathId: The FieldPathId of the field in the hierarchy; use fieldPathId.$id to get the HTML id string.
• onExpand: Callback to call when the user wants to render one additional level; receives the field's id string.
• schema: The schema object for the field at the cycle boundary.
• uiSchema: The uiSchema object for this field.
• registry: The registry object.

DescriptionFieldTemplate Copy Chapter

Each theme implements a DescriptionFieldTemplate used to render the description of a field.
If you want to customize how descriptions are rendered you can.

import { DescriptionFieldProps, RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
  title: 'My input',
  description: 'input description',
};

function DescriptionFieldTemplate(props: DescriptionFieldProps) {
  const { description, id } = props;
  return (
    <details id={id}>
      <summary>Description</summary>
      {description}
    </details>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ DescriptionFieldTemplate }} />,
  document.getElementById('app'),
);

The following props are passed to the DescriptionFieldTemplate:

• description: The description of the field being rendered.
• id: The id of the field in the hierarchy.
• schema: The schema object for the field.
• uiSchema: The uiSchema object for the field.
• registry: The registry object.

ErrorListTemplate Copy Chapter

The ErrorListTemplate is the template that renders the all the errors associated with the fields in the Form, at the top.
Each theme implements a ErrorListTemplate used to render its errors using components for the theme's toolkit.
If you want to customize how all the errors are rendered you can.

import { ErrorListProps, RJSFValidationError, RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
  title: 'My input',
  description: 'input description',
};

function ErrorListTemplate(props: ErrorListProps) {
  const { errors } = props;
  return (
    <details id={id}>
      <summary>Errors</summary>
      <ul>
        {errors.map((error: RJSFValidationError, i: number) => {
          return (
            <li key={i} className='error'>
              {error.stack}
            </li>
          );
        })}
      </ul>
    </details>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ ErrorListTemplate }} />,
  document.getElementById('app'),
);

The following props are passed to the ErrorListTemplate:

• schema: The schema that was passed to Form
• uiSchema: The uiSchema that was passed to Form
• errors: An array of all errors in this Form.
• errorSchema: The ErrorSchema constructed by Form

FallbackFieldTemplate Copy Chapter

The FallbackFieldTemplate is the template that renders opt-in fallback UI to control fields of unknown or unhandled types. Usage of this feature is controlled by the useFallbackUiForUnsupportedType Form prop.

import { FallbackFieldTemplateProps, RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'unknownType',
  title: 'My input',
};

function FallbackFieldTemplate(props: FallbackFieldTemplateProps) {
  const { typeSelector, schemaField } = props;
  return (
    <div className={'row'}>
      <div className={'col-xs-4'}>{typeSelector}</div>
      <div className={'col-xs-8'}>{schemaField}</div>
    </div>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ FallbackFieldTemplate }} />,
  document.getElementById('app'),
);

The following props are passed to the FallbackFieldTemplate:

• schema: The schema for the field
• uiSchema: The uiSchema for the field
• registry: The Registry object
  1

FieldErrorTemplate Copy Chapter

The FieldErrorTemplate is the template that renders all the errors associated a single field.
If you want to customize how the errors are rendered you can.

import { FieldErrorProps, RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
  title: 'My input',
  description: 'input description',
};

function FieldErrorTemplate(props: FieldErrorProps) {
  const { errors } = props;
  return (
    <details id={id}>
      <summary>Errors</summary>
      <ul>
        {errors.map((error: string, i: number) => {
          return (
            <li key={i} className='error'>
              {error.stack}
            </li>
          );
        })}
      </ul>
    </details>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ FieldErrorTemplate }} />,
  document.getElementById('app'),
);

The following props are passed to the FieldErrorTemplate:

• schema: The schema for the field
• uiSchema: The uiSchema for the field
• fieldPathId: The FieldPathId of the field in the hierarchy
• errors: An array of all errors for this field
• errorSchema: The ErrorSchema for this field
• registry: The Registry object

FieldHelpTemplate Copy Chapter

The FieldHelpTemplate is the template that renders the help associated a single field.
If you want to customize how the help is rendered you can.

import { FieldHelpProps, RJSFSchema, helpId } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
  title: 'My input',
  description: 'input description',
};

function FieldHelpTemplate(props: FieldHelpProps) {
  const { help, fieldPathId } = props;
  const id = helpId(fieldPathId);
  return <aside id={id}>{help}</aside>;
}

render(
  <Form schema={schema} validator={validator} templates={{ FieldHelpTemplate }} />,
  document.getElementById('app'),
);

The following props are passed to the FieldHelpTemplate:

• schema: The schema for the field
• uiSchema: The uiSchema for the field
• fieldPathId: The FieldPathId of the field in the hierarchy
• help: The help information to be rendered
• registry: The Registry object

FieldTemplate Copy Chapter

To take control over the inner organization of each field (each form row), you can define a field template for your form.

A field template is basically a React stateless component being passed field-related props, allowing you to structure your form row as you like.

import { FieldTemplateProps, RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
};

function CustomFieldTemplate(props: FieldTemplateProps) {
  const { id, classNames, style, label, help, required, description, errors, children } = props;
  return (
    <div className={classNames} style={style}>
      <label htmlFor={id}>
        {label}
        {required ? '*' : null}
      </label>
      {description}
      {children}
      {errors}
      {help}
    </div>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ FieldTemplate: CustomFieldTemplate }} />,
  document.getElementById('app'),
);

You also can provide your own field template to a uiSchema by specifying a ui:FieldTemplate property with your Component :

import { UiSchema } from '@rjsf/utils';
import CustomFieldTemplate from './CustomFieldTemplate';

const uiSchema: UiSchema = {
  'ui:FieldTemplate': CustomFieldTemplate,
};

or a string value from the Registry :

import { UiSchema } from '@rjsf/utils';

const uiSchema: UiSchema = {
  'ui:FieldTemplate': 'CustomFieldTemplate',
};

If you want to handle the rendering of each element yourself, you can use the props rawHelp, rawDescription and rawErrors.

The following props are passed to a custom field template component:

• id: The id of the field in the hierarchy. You can use it to render a label targeting the wrapped widget.
• classNames: A string containing the base Bootstrap CSS classes, merged with any custom ones defined in your uiSchema.
• style: An object containing the StyleHTMLAttributes defined in the uiSchema.
• label: The computed label for this field, as a string.
• description: A component instance rendering the field description, if one is defined (this will use any custom DescriptionFieldTemplate defined in the templates passed to the Form).
• rawDescription: A string containing any ui:description uiSchema directive defined.
• children: The field or widget component instance for this field row.
• errors: A component instance listing any encountered errors for this field.
• rawErrors: An array of strings listing all generated error messages from encountered errors for this field.
• help: A component instance rendering any ui:help uiSchema directive defined.
• rawHelp: A string containing any ui:help uiSchema directive defined. NOTE: rawHelp will be undefined if passed ui:help is a React component instead of a string.
• hidden: A boolean value stating if the field should be hidden.
• required: A boolean value stating if the field is required.
• readonly: A boolean value stating if the field is read-only.
• hideError: A boolean value stating if the field is hiding its errors
• disabled: A boolean value stating if the field is disabled.
• displayLabel: A boolean value stating if the label should be rendered or not. This is useful for nested fields in arrays where you don't want to clutter the UI.
• schema: The schema object for this field.
• uiSchema: The uiSchema object for this field.
• onChange: The value change event handler; Can be called with a new value to change the value for this field.
• formData: The formData for this field.
• registry: The registry object.

Note: you can only define a single global field template for a form, but you can set individual field templates per property using "ui:FieldTemplate".

GridTemplate Copy Chapter

The GridTemplate is the template that renders a theme dependent Grid for either a row or column.
While it has only two explicit properties, it extends the GenericObjectTemplate in order to support passing any of the properties associated with a Grid implementation for any theme.
If you want to customize how grids are rendered you can.

import { Grid2 } from '@mui/material';
import { GridTemplateProps } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';
import classNames from 'classnames';

const schema: RJSFSchema = {
  type: 'string',
  title: 'My input',
  description: 'input description',
};

function GridTemplate(props: FieldHelpProps) {
  const { children, column, className, ...rest } = props;
  return (
    <Grid2 item={column} {...rest} className={`${className} my-custom-grid-styling`}>
      {children}
    </Grid2>
  );
}

render(<Form schema={schema} validator={validator} templates={{ GridTemplate }} />, document.getElementById('app'));

The following props are passed to the GridTemplate:

• children: The contents of the grid template
• column: Optional flag indicating whether the grid element represents a column, necessary for themes which have components for Rows vs Column

MultiSchemaFieldTemplate Copy Chapter

Each theme implements a MultiSchemaFieldTemplate used to render the layout of a MultiSchemaField, i.e. a field described by a oneOf or anyOf schema.
The template typically renders a Widget used to select the schema to use, as well as a field for the selected schema.

import { MultiSchemaFieldTemplateProps, RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'object',
  properties: {
    myField: {
      oneOf: [
        {
          type: 'string',
          title: 'String Field',
          description: 'A field that accepts a string',
        },
        {
          type: 'number',
          title: 'Number Field',
          description: 'A field that accepts a number',
        },
      ],
    },
  },
};

function MultiSchemaFieldTemplate(props: MultiSchemaFieldTemplateProps) {
  const { selector, optionSchemaField } = props;
  return (
    <div className='my-multi-schema-field-class'>
      {selector}
      <hr />
      {optionSchemaField}
    </div>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ MultiSchemaFieldTemplate }} />,
  document.getElementById('app'),
);

The following props are passed to the MultiSchemaFieldTemplate:

• selector: The rendered Widget used to select a multischema option.
• optionSchemaField: The rendered SchemaField representing the selected option.
• schema: The schema object for the field.
• uiSchema: The uiSchema object for the field.
• registry: The registry object.

ObjectFieldTemplate Copy Chapter

import { ObjectFieldTemplateProps, RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'object',
  title: 'Object title',
  description: 'Object description',
  properties: {
    name: {
      type: 'string',
    },
    age: {
      type: 'number',
    },
  },
};

function ObjectFieldTemplate(props: ObjectFieldTemplateProps) {
  return (
    <div>
      {props.title}
      {props.description}
      {props.properties.map((element) => (
        <div className='property-wrapper'>{element.content}</div>
      ))}
    </div>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ ObjectFieldTemplate }} />,
  document.getElementById('app'),
);

You also can provide your own field template to a uiSchema by specifying a ui:ObjectFieldTemplate property with your Component :

import { UiSchema } from '@rjsf/utils';
import ObjectFieldTemplate from './ObjectFieldTemplate';

const uiSchema: UiSchema = {
  'ui:ObjectFieldTemplate': ObjectFieldTemplate,
};

or a string value from the Registry :

import { UiSchema } from '@rjsf/utils';

const uiSchema: UiSchema = {
  'ui:ObjectFieldTemplate': 'ObjectFieldTemplate',
};

Please see the customObject.tsx sample from the playground for a better example.

The following props are passed to each ObjectFieldTemplate as defined by the ObjectFieldTemplateProps in @rjsf/utils:

• title: A string value containing the title for the object.
• description: A string value containing the description for the object.
• disabled: A boolean value stating if the object is disabled.
• properties: An array of object representing the properties in the object. Each of the properties represent a child with properties described below.
• onAddProperty: () => void: Callback to use in order to add an new additionalProperty to the object field (to be used with additionalProperties and patternProperties)
• readonly: A boolean value stating if the object is read-only.
• required: A boolean value stating if the object is required.
• hideError: A boolean value stating if the field is hiding its errors.
• schema: The schema object for this object.
• uiSchema: The uiSchema object for this object field.
• fieldPathId: The FieldPathId of the field in the hierarchy
• errorSchema: The optional validation errors in the form of an ErrorSchema
• formData: The form data for the object.
• registry: The registry object.

The following props are part of each element in properties:

• content: The html for the property's content.
• name: A string representing the property name.
• disabled: A boolean value stating if the object property is disabled.
• readonly: A boolean value stating if the property is read-only.
• hidden: A boolean value stating if the property should be hidden.

Note: Array and object field templates are always rendered inside the FieldTemplate. To fully customize an object field template, you may need to specify both ui:FieldTemplate and ui:ObjectFieldTemplate.

OptionalDataControlsTemplate Copy Chapter

Each theme implements a OptionalDataControlsTemplate used to render the Optional Data Controls when that feature has been enabled

/* Detailed source-code truncated for AI context efficiency. */

The following props are passed to each OptionalDataControlsTemplate as defined by the OptionalDataControlsTemplateProps in @rjsf/utils:

• id: The generated id for this Optional Data Control instance.
• label: The label to use for the Optional Data Control
• onAddClick: Optional callback to call when clicking on the Optional Data Control to add data
• onRemoveClick: Optional callback to call when clicking on the Optional Data Control to remove data
• schema: The schema object for this object.
• uiSchema: The uiSchema object for this object field.
• registry: The registry object.

TitleFieldTemplate Copy Chapter

Each theme implements a TitleFieldTemplate used to render the title of a field.
If you want to customize how titles are rendered you can.

import { RJSFSchema, TitleFieldProps } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
  title: 'My input',
  description: 'input description',
};

function TitleFieldTemplate(props: TitleFieldProps) {
  const { id, required, title } = props;
  return (
    <header id={id}>
      {title}
      {required && <mark>*</mark>}
    </header>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ TitleFieldTemplate }} />,
  document.getElementById('app'),
);

The following props are passed to each TitleFieldTemplate:

• id: The id of the field in the hierarchy.
• title: The title of the field being rendered.
• schema: The schema object for the field.
• uiSchema: The uiSchema object for the field.
• required: A boolean value stating if the field is required
• registry: The registry object.

UnsupportedFieldTemplate Copy Chapter

The UnsupportedField component is used to render a field in the schema is one that is not supported by react-jsonschema-form.
If you want to customize how an unsupported field is rendered (perhaps for localization purposes) you can.

import { RJSFSchema, UnsupportedFieldProps } from '@rjsf/utils';
import { FormattedMessage } from 'react-intl';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'invalid',
};

function UnsupportedFieldTemplate(props: UnsupportedFieldProps) {
  const { schema, reason } = props;
  return (
    <div>
      <FormattedMessage defaultMessage='Unsupported field schema, reason = {reason}' value={{ reason }} />
      <pre>{JSON.stringify(schema, null, 2)}</pre>
    </div>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ UnsupportedFieldTemplate }} />,
  document.getElementById('app'),
);

The following props are passed to each UnsupportedFieldTemplate:

• schema: The schema object for this unsupported field.
• fieldPathId: The FieldPathId of the field in the hierarchy
• reason: The reason why the schema field has an unsupported type.
• registry: The registry object.

WrapIfAdditionalTemplate Copy Chapter

The WrapIfAdditionalTemplate is used by the FieldTemplate to conditionally render additional controls if additionalProperties or patternProperties are present in the schema.
You may customize WrapIfAdditionalTemplate if you wish to change the layout or behavior of user-controlled additionalProperties and patternProperties.

import { RJSFSchema, WrapIfAdditionalTemplateProps } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'object',
  additionalProperties: true,
};

function WrapIfAdditionalTemplate(props: WrapIfAdditionalTemplateProps) {
  const {
    id,
    label,
    onKeyRename,
    onKeyRenameBlur,
    onRemoveProperty,
    schema,
    children,
    uiSchema,
    registry,
    classNames,
    style,
  } = props;
  const { RemoveButton } = registry.templates.ButtonTemplates;
  const additional = ADDITIONAL_PROPERTY_FLAG in schema;

  if (!additional) {
    return <div>{children}</div>;
  }

  return (
    <div className={classNames} style={style}>
      <label label={keyLabel} id={`${id}-key`}>
        Custom Field Key
      </label>
      <input className='form-control' type='text' id={`${id}-key`} onBlur={onKeyRenameBlur} defaultValue={label} />
      <div>{children}</div>
      <RemoveButton onClick={onRemoveProperty} uiSchema={uiSchema} />
    </div>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ WrapIfAdditionalTemplate }} />,
  document.getElementById('app'),
);

The following props are passed to the WrapIfAdditionalTemplate:

• children: The children of the component, typically specified by the FieldTemplate.

• id: The id of the field in the hierarchy. You can use it to render a label targeting the wrapped widget.

• classNames: A string containing the base Bootstrap CSS classes, merged with any custom ones defined in your uiSchema.

• style: An object containing the StyleHTMLAttributes defined in the uiSchema.

• label: The computed label for this field, as a string.

• required: A boolean value stating if the field is required.

• readonly: A boolean value stating if the field is read-only.

• disabled: A boolean value stating if the field is disabled.

• schema: The schema object for this field.

• uiSchema: The uiSchema object for this field.

• onKeyRename: Callback used to handle the changing of an additional property key's name with the new value

• onKeyRenameBlur: Callback used to handle the changing of an additional property key's name when the input is blurred. The event's target's value will be used as the new value. Its a wrapper callback around onKeyRename

• onRemoveProperty: Callback used to handle the removal of the additionalProperty

ButtonTemplates Copy Chapter

There are several buttons that are potentially rendered in the Form.
Each of these buttons have been customized in the themes, and can be customized by you as well.
All but one of these buttons (i.e. the SubmitButton) are rendered currently as icons with title text for a description.

Each button template (except for the SubmitButton) accepts, as props, the standard HTML button attributes along with the following:

• iconType: An alternative specification for the type of the icon button.
• icon: The name representation or actual react element implementation for the icon.
• uiSchema: The uiSchema object for this field.
• registry: The registry object.

AddButton Copy Section

The AddButton is used to render an add action on a Form for both a new additionalProperties or patternProperties element for an object or a new element in an array.
You can customize the AddButton to render something other than the icon button that is provided by a theme as follows:

import React from 'react';
import { IconButtonProps, RJSFSchema } from '@rjsf/utils';
import { FormattedMessage } from 'react-intl';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
};

function AddButton(props: IconButtonProps) {
  const { icon, iconType, ...btnProps } = props;
  return (
    <button {...btnProps}>
      {icon} <FormattedMessage defaultMessage='Add' />
    </button>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ ButtonTemplates: { AddButton } }} />,
  document.getElementById('app'),
);

MoveDownButton Copy Section

The MoveDownButton is used to render a move down action on a Form for elements in an array.
You can customize the MoveDownButton to render something other than the icon button that is provided by a theme as follows:

import React from 'react';
import { IconButtonProps, RJSFSchema } from '@rjsf/utils';
import { FormattedMessage } from 'react-intl';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
};

function MoveDownButton(props: IconButtonProps) {
  const { icon, iconType, ...btnProps } = props;
  return (
    <button {...btnProps}>
      {icon} <FormattedMessage defaultMessage='Move Down' />
    </button>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ ButtonTemplates: { MoveDownButton } }} />,
  document.getElementById('app'),
);

MoveUpButton Copy Section

The MoveUpButton is used to render a move up action on a Form for elements in an array.
You can customize the MoveUpButton to render something other than the icon button that is provided by a theme as follows:

import React from 'react';
import { IconButtonProps, RJSFSchema } from '@rjsf/utils';
import { FormattedMessage } from 'react-intl';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
};

function MoveUpButton(props: IconButtonProps) {
  const { icon, iconType, ...btnProps } = props;
  return (
    <button {...btnProps}>
      {icon} <FormattedMessage defaultMessage='Move Up' />
    </button>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ ButtonTemplates: { MoveUpButton } }} />,
  document.getElementById('app'),
);

RemoveButton Copy Section

The RemoveButton is used to render a remove action on a Form for both a existing additionalProperties or patternProperties element for an object or an existing element in an array.
You can customize the RemoveButton to render something other than the icon button that is provided by a theme as follows:

import React from 'react';
import { IconButtonProps, RJSFSchema } from '@rjsf/utils';
import { FormattedMessage } from 'react-intl';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
};

function RemoveButton(props: IconButtonProps) {
  const { icon, iconType, ...btnProps } = props;
  return (
    <button {...btnProps}>
      {icon} <FormattedMessage defaultMessage='Remove' />
    </button>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ ButtonTemplates: { RemoveButton } }} />,
  document.getElementById('app'),
);

SubmitButton Copy Section

The SubmitButton is already very customizable via the UISchemaSubmitButtonOptions capabilities in the uiSchema but it can also be fully customized as you see fit.

NOTE: However you choose to implement this, making it something other than a submit type button may result in the Form not submitting when pressed.
You could also choose to provide your own submit button as the children prop of the Form should you so choose.

import React from 'react';
import { getSubmitButtonOptions, RJSFSchema, SubmitButtonProps } from '@rjsf/utils';
import { FormattedMessage } from 'react-intl';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
};

function SubmitButton(props: SubmitButtonProps) {
  const { uiSchema } = props;
  const { norender } = getSubmitButtonOptions(uiSchema);
  if (norender) {
    return null;
  }
  return (
    <button type='submit'>
      <FormattedMessage defaultMessage='Okay' />
    </button>
  );
}

render(
  <Form schema={schema} validator={validator} templates={{ ButtonTemplates: { SubmitButton } }} />,
  document.getElementById('app'),
);

The following prop is passed to a SubmitButton:

• uiSchema: The uiSchema object for this field, used to extract the UISchemaSubmitButtonOptions.
• registry: The registry object.

Custom Templates Copy Chapter

You can now add custom components to the registry and reference them in your uiSchema using string keys.

Adding Custom Templates to the Registry Copy Section

import CustomArrayFieldTemplate from './CustomArrayFieldTemplate';
import { UiSchema } from '@rjsf/utils';

// Add the custom template to the registry
const registry = { templates: { CustomArrayFieldTemplate } };

// Use the custom template in the uiSchema
const uiSchema: UiSchema = { 'ui:ArrayFieldTemplate': 'CustomArrayFieldTemplate' };

Packages Docs Docs Advanced Customization Custom Themes (`packages/docs/docs/advanced-customization/custom-themes.md`) Copy Section

Custom Themes

The withTheme component provides an easy way to extend the functionality of react-jsonschema-form by passing in a theme object that defines custom/overridden widgets and fields, as well as any of the other possible properties of the standard rjsf Form component.
This theme-defining object is passed as the only parameter to the HOC (withTheme(ThemeObj)), and the HOC will return a themed-component which you use instead of the standard Form component.

Usage Copy Chapter

import React, { Component } from 'react';
import validator from '@rjsf/validator-ajv8';
import { withTheme, ThemeProps } from '@rjsf/core';

const theme: ThemeProps = { widgets: { test: () => <div>test</div> } };

const ThemedForm = withTheme(theme);

const Demo = () => <ThemedForm schema={schema} uiSchema={uiSchema} validator={validator} />;

Theme object properties Copy Chapter

The Theme object consists of the same properties as the rjsf Form component (such as widgets, fields and templates).
The themed-Form component merges together any theme-specific widgets, fields and templates with the default widgets, fields and templates.
For instance, providing a single widget in widgets will merge this widget with all the default widgets of the rjsf Form component, but overrides the default if the theme's widget's name matches the default widget's name.
Thus, for each default widget or field not specified/overridden, the themed-form will rely on the defaults from the rjsf Form.
Note that you are not required to pass in either custom widgets, fields or templates when using the custom-themed HOC component;
you can essentially redefine the default Form by simply doing const Form = withTheme({});.

Widgets and fields Copy Section

widgets and fields should be in the same format as shown here.

Example theme with custom widget:

import { WidgetProps, RegistryWidgetsType } from '@rjsf/utils';
import { ThemeProps } from '@rjsf/core';

const MyCustomWidget = (props: WidgetProps) => {
  return (
    <input
      type='text'
      className='custom'
      value={props.value}
      required={props.required}
      onChange={(event) => props.onChange(event.target.value)}
    />
  );
};

const myWidgets: RegistryWidgetsType = {
  myCustomWidget: MyCustomWidget,
};

const ThemeObject: ThemeProps = { widgets: myWidgets };
export default ThemeObject;

The above can be similarly done for fields and templates.

Templates Copy Section

Each template should be passed into the theme object via the templates object just as you would into the rjsf Form component. Here is an example of how to use a custom ArrayFieldTemplate and ErrorListTemplate in the theme object:

import { ArrayFieldTemplateProps, ErrorListProps } from '@rjsf/utils';
import { ThemeProps } from '@rjsf/core';

function MyArrayFieldTemplate(props: ArrayFieldTemplateProps) {
  return (
    <div>
      {props.items.map((element) => element.children)}
      {props.canAdd && <button type='button' onClick={props.onAddClick}></button>}
    </div>
  );
}

function MyErrorListTemplate(props: ErrorListProps) {
  const { errors } = props;
  return (
    <ul>
      {errors.map((error) => (
        <li key={error.stack}>{error.stack}</li>
      ))}
    </ul>
  );
}

const ThemeObject: ThemeProps = {
  templates: {
    ArrayFieldTemplate: MyArrayFieldTemplate,
    ErrorListTemplate: MyErrorListTemplate,
  },
  widgets: myWidgets,
};

export default ThemeObject;

Overriding other Form props Copy Chapter

Just as the theme can override widgets, fields, any of the templates, and set default values to properties like showErrorList, you can do the same with the instance of the withTheme() Form component.

import { ThemeProps } from '@rjsf/core';

const ThemeObject: ThemeProps = {
  templates: {
    ArrayFieldTemplate: MyArrayFieldTemplate,
  },
  fields: myFields,
  showErrorList: false,
  widgets: myWidgets,
};

Thus, the user has higher priority than the withTheme HOC, and the theme has higher priority than the default values of the rjsf Form component (User > Theme > Defaults).

Packages Docs Docs Advanced Customization Custom Widgets Fields (`packages/docs/docs/advanced-customization/custom-widgets-fields.md`) Copy Section

Custom Widgets and Fields

The API allows to specify your own custom widget and field components:

• A widget represents a HTML tag for the user to enter data, eg. input, select, etc.
• A field usually wraps one or more widgets and most often handles internal field state; think of a field as a form row, including the labels.

Customizing the default fields and widgets Copy Chapter

You can override any default field and widget, including the internal widgets like the CheckboxWidget that BooleanField
renders for boolean values. You can override any field and widget just by providing the customized fields/widgets in the
fields and widgets props:

import { RJSFSchema, UiSchema, WidgetProps, RegistryWidgetsType } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'boolean',
  default: true,
};

const uiSchema: UiSchema = {
  'ui:widget': 'checkbox',
};

const CustomCheckbox = function (props: WidgetProps) {
  return (
    <button id='custom' className={props.value ? 'checked' : 'unchecked'} onClick={() => props.onChange(!props.value)}>
      {String(props.value)}
    </button>
  );
};

const widgets: RegistryWidgetsType = {
  CheckboxWidget: CustomCheckbox,
};

render(
  <Form schema={schema} uiSchema={uiSchema} validator={validator} widgets={widgets} />,
  document.getElementById('app'),
);

This allows you to create a reusable customized form class with your custom fields and widgets:

import { RegistryFieldsType, RegistryWidgetsType } from '@rjsf/utils';
import { FormProps } from '@rjsf/core';

const customFields: RegistryFieldsType = { StringField: CustomString };
const customWidgets: RegistryWidgetsType = { CheckboxWidget: CustomCheckbox };

function MyForm(props: FormProps) {
  return <Form fields={customFields} widgets={customWidgets} {...props} />;
}

The default fields you can override are:

• ArrayField
• ArraySchemaField
• BooleanField
• DescriptionField
• OneOfField
• AnyOfField
• LayoutGridField
• LayoutMultiSchemaField
• LayoutHeaderField
• NullField
• NumberField
• ObjectField
• SchemaField
• StringField
• TitleField
• UnsupportedField
• FallbackField
• CyclicSchemaField

The default widgets you can override are:

• AltDateTimeWidget
• AltDateWidget
• CheckboxesWidget
• CheckboxWidget
• ColorWidget
• DateTimeWidget
• DateWidget
• EmailWidget
• FileWidget
• HiddenWidget
• PasswordWidget
• RadioWidget
• RangeWidget
• SelectWidget
• TextareaWidget
• TextWidget
• TimeWidget
• UpDownWidget
• URLWidget

Raising errors from within a custom widget or field Copy Chapter

You can raise custom 'live validation' errors by overriding the onChange method to provide feedback while users are actively changing the form data.
If you do set errors this way, you must also clear them this way by passing undefined to the onChange() for the errorSchema parameter.

:::warning

While these errors are retained during validation, it is still preferred for you to use the customValidate Form prop mechanism instead.

:::

import { ErrorSchema, RJSFSchema, UiSchema, WidgetProps, RegistryWidgetsType } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'text',
  default: 'hello',
};

const uiSchema: UiSchema = {
  'ui:widget': 'text',
};

const CustomTextWidget = function (props: WidgetProps) {
  const { id, value } = props;
  const raiseErrorOnChange = ({ target: { value } }: ChangeEvent<HTMLInputElement>) => {
    let raiseError: ErrorSchema | undefined;
    if (value !== 'test') {
      raiseError = {
        __errors: ['Value must be "test"'],
      };
    }
    props.onChange(value, [], raiseError, id);
  };

  return <input id={id} onChange={raiseErrorOnChange} value={value || ''} />;
};

const widgets: RegistryWidgetsType = {
  TextWidget: CustomTextWidget,
};

render(
  <Form schema={schema} uiSchema={uiSchema} validator={validator} widgets={widgets} />,
  document.getElementById('app'),
);

This creates a custom text widget that raises an error if the input value does not match 'test'.

Adding your own custom widgets Copy Chapter

You can provide your own custom widgets to a uiSchema for the following json data types:

• string
• number
• integer
• boolean
• array

import { RJSFSchema, UiSchema, WidgetProps } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: Schema = {
  type: 'string',
};

const uiSchema: UiSchema = {
  'ui:widget': (props: WidgetProps) => {
    return (
      <input
        type='text'
        className='custom'
        value={props.value}
        required={props.required}
        onChange={(event) => props.onChange(event.target.value)}
      />
    );
  },
};

render(<Form schema={schema} uiSchema={uiSchema} validator={validator} />, document.getElementById('app'));

The following props are passed to custom widget components:

• id: The generated id for this widget, used to provide unique names and ids for the HTML field elements rendered by widgets;
• name: The unique name of the field, usually derived from the name of the property in the JSONSchema; Provided in support of custom widgets;
• schema: The JSONSchema subschema object for this widget;
• uiSchema: The uiSchema for this widget;
• value: The current value for this widget;
• placeholder: The placeholder for the widget, if any;
• required: The required status of this widget;
• disabled: A boolean value stating if the widget is disabled;
• readonly: A boolean value stating if the widget is read-only;
• autofocus: A boolean value stating if the widget should autofocus;
• label: The computed label for this widget, as a string
• hideLabel: A boolean value, if true, will cause the label to be hidden. This is useful for nested fields where you don't want to clutter the UI. Customized via label in the UiSchema;
• multiple: A boolean value stating if the widget can accept multiple values;
• onChange: The value change event handler; call it with the new value every time it changes;
• onKeyChange: The key change event handler (only called for fields with additionalProperties); pass the new value every time it changes;
• onBlur: The input blur event handler; call it with the widget id and value;
• onFocus: The input focus event handler; call it with the widget id and value;
• options: A map of options passed as a prop to the component (see Custom widget options).
• options.enumOptions: For enum fields, this property contains the list of options for the enum as an array of { label, value } objects. If the enum is defined using the oneOf/anyOf syntax, the entire schema object for each option is appended onto the { schema, label, value } object.
• rawErrors: An array of strings listing all generated error messages from encountered errors for this widget.
• registry: A registry object (read next).

Custom component registration Copy Section

Alternatively, you can register them all at once by passing the widgets prop to the Form component, and reference their identifier from the uiSchema:

import { RJSFSchema, UiSchema, WidgetProps, RegistryWidgetsType } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const MyCustomWidget = (props: WidgetProps) => {
  return (
    <input
      type='text'
      className='custom'
      value={props.value}
      required={props.required}
      onChange={(event) => props.onChange(event.target.value)}
    />
  );
};

const widgets: RegistryWidgetsType = {
  myCustomWidget: MyCustomWidget,
};

const schema: RJSFSchema = {
  type: 'string',
};

const uiSchema: UiSchema = {
  'ui:widget': 'myCustomWidget',
};

render(
  <Form schema={schema} uiSchema={uiSchema} validator={validator} widgets={widgets} />,
  document.getElementById('app'),
);

This is useful if you expose the uiSchema as pure JSON, which can't carry functions.

Custom widget options Copy Section

If you need to pass options to your custom widget, you can add a ui:options object containing those properties. If the widget has defaultProps, the options will be merged with the (optional) options object from defaultProps:

import { RJSFSchema, UiSchema, WidgetProps } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
};

function MyCustomWidget(props: WidgetProps) {
  const { options } = props;
  const { color, backgroundColor } = options;
  return <input style={{ color, backgroundColor }} />;
}

MyCustomWidget.defaultProps = {
  options: {
    color: 'red',
  },
};

const uiSchema: UiSchema = {
  'ui:widget': MyCustomWidget,
  'ui:options': {
    backgroundColor: 'yellow',
  },
};

// renders red on yellow input
render(<Form schema={schema} uiSchema={uiSchema} validator={validator} />, document.getElementById('app'));

Note: This also applies to registered custom components.

Customizing widgets' text input Copy Section

All the widgets that render a text input use the BaseInputTemplate component internally. If you need to customize all text inputs without customizing all widgets individually, you can provide a BaseInputTemplate component in the templates property of Form (see Custom Templates).

Wrapping an existing widget to customize it Copy Section

Sometimes you just need to customize the properties that are passed to an existing widget.
The way to do this varies based upon whether you are using core or some other theme (such as mui).

Here is an example of modifying the SelectWidget to change the ordering of enumOptions:

import { WidgetProps } from '@rjsf/utils';
import { getDefaultRegistry } from '@rjsf/core';
import { Widgets } from '@rjsf/mui';

import myOptionsOrderFunction from './myOptionsOrderFunction';

const {
  widgets: { SelectWidget },
} = getDefaultRegistry(); // To get widgets from core
// const { SelectWidget } = Widgets; // To get widgets from a theme do this

function MySelectWidget(props: WidgetProps) {
  const { options } = props;
  let { enumOptions } = options;
  // Reorder the `enumOptions` however you want
  enumOptions = myOptionsOrderFunction(enumOptions);
  return <SelectWidget {...props} options={{ ...options, enumOptions }} />;
}

Custom field components Copy Chapter

You can provide your own field components to a uiSchema for basically any json schema data type, by specifying a ui:field property.

For example, let's create and register a dumb geo component handling a latitude and a longitude:

import { RJSFSchema, UiSchema, FieldProps, RegistryFieldsType } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'object',
  required: ['lat', 'lon'],
  properties: {
    lat: { type: 'number' },
    lon: { type: 'number' },
  },
};

// Define a custom component for handling the root position object
class GeoPosition extends React.Component<FieldProps> {
  constructor(props: FieldProps) {
    super(props);
    this.state = { ...props.formData };
  }

  onChange(name) {
    return (event) => {
      this.setState(
        {
          [name]: parseFloat(event.target.value),
        },
        () => this.props.onChange(this.state),
      );
    };
  }

  render() {
    const { lat, lon } = this.state;
    return (
      <div>
        <input type='number' value={lat} onChange={this.onChange('lat')} />
        <input type='number' value={lon} onChange={this.onChange('lon')} />
      </div>
    );
  }
}

// Define the custom field component to use for the root object
const uiSchema: UiSchema = { 'ui:field': 'geo' };

// Define the custom field components to register; here our "geo"
// custom field component
const fields: RegistryFieldsType = { geo: GeoPosition };

// Render the form with all the properties we just defined passed
// as props
render(
  <Form schema={schema} uiSchema={uiSchema} validator={validator} fields={fields} />,
  document.getElementById('app'),
);

Note: Registered fields can be reused across the entire schema.

Field props Copy Section

A field component will always be passed the following props:

• schema: The JSON subschema object for this field;
• uiSchema: The uiSchema for this field;
• idSchema: The FieldPathId of the field in the hierarchy
• formData: The data for this field;
• errorSchema: The tree of errors for this field and its children;
• registry: A registry object (read next).
• required: The required status of this field;
• disabled: A boolean value stating if the field is disabled;
• readonly: A boolean value stating if the field is read-only;
• autofocus: A boolean value stating if the field should autofocus;
• name: The unique name of the field, usually derived from the name of the property in the JSONSchema
• rawErrors: `An array of strings listing all generated error messages from encountered errors for this field
• onChange: The field change event handler; called with the updated field value, the optional change path for the value (defaults to an empty array), an optional ErrorSchema and the optional id of the field being changed
• onBlur: The input blur event handler; call it with the field id and value;
• onFocus: The input focus event handler; call it with the field id and value;

The `registry` object Copy Chapter

The registry is an object containing the registered core, theme and custom fields and widgets as well as the root schema, form context, schema utils.

• fields: The set of all fields used by the Form. Includes fields from core, theme-specific fields and any custom registered fields;
• widgets: The set of all widgets used by the Form. Includes widgets from core, theme-specific widgets and any custom registered widgets, if any;
• templates: The set of templates used by the Form. Includes templates from core, theme-specific templates and any custom registered templates
• rootSchema: The root schema, as passed to the Form, which can contain referenced definitions;
• schemaUtils: The current implementation of the SchemaUtilsType (from @rjsf/utils) in use by the Form. Used to call any of the validation-schema-based utility functions.
• translateString: The string translation function to use when displaying any of the RJSF strings in templates, fields or widgets
• globalFormOptions: The global Form Options that are available for all templates, fields and widgets to access
• globalUiOptions: The optional global UI Options that are available for all templates, fields and widgets to access

The registry is passed down the component tree, so you can access it from your custom field, custom widget, custom template and SchemaField components.

Custom SchemaField Copy Section

Warning: This is a powerful feature as you can override the whole form behavior and easily mess it up. Handle with care.

You can provide your own implementation of the SchemaField base React component for rendering any JSONSchema field type, including objects and arrays. This is useful when you want to augment a given field type with supplementary powers.

To proceed so, pass a fields object having a SchemaField property to your Form component; here's an example:

import { RJSFSchema, FieldProps, RegistryFieldsType } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const CustomSchemaField = function (props: FieldProps) {
  return (
    <div id='custom'>
      <p>Yeah, I'm pretty dumb.</p>
      <div>My props are: {JSON.stringify(props)}</div>
    </div>
  );
};

const fields: RegistryFieldsType = {
  SchemaField: CustomSchemaField,
};

const schema: RJSFSchema = {
  type: 'string',
};

render(<Form schema={schema} validator={validator} fields={fields} />, document.getElementById('app'));

If you're curious how this could ever be useful, have a look at the Kinto formbuilder repository to see how it's used to provide editing capabilities to any form field.

Props passed to a custom SchemaField are the same as the ones passed to a custom field.

Custom ArraySchemaField Copy Section

Everything that was mentioned above for a Custom SchemaField applies, but this is only used to render the Array item children that are then passed to the ArrayFieldItemTemplate.
By default, ArraySchemaField is not actually implemented in the fields list since ArrayField falls back to SchemaField if ArraySchemaField is not provided.
If you want to customize how the individual items for an array are rendered, provide your implementation of ArraySchemaField as a fields override.

import { RJSFSchema, UiSchema, FieldProps, RegistryFieldsType } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const CustomArraySchemaField = function (props: FieldProps) {
  const { index, registry } = props;
  const { SchemaField } = registry.fields;
  const name = `Index ${index}`;
  return <SchemaField {...props} name={name} />;
};

const fields: RegistryFieldsType = {
  ArraySchemaField: CustomArraySchemaField,
};

const schema: RJSFSchema = {
  type: 'string',
};

render(<Form schema={schema} validator={validator} fields={fields} />, document.getElementById('app'));

Custom Field by Id Copy Section

Warning: This is a powerful feature as you can override the whole form behavior and easily mess it up. Handle with care.

You can provide your own implementation of the field component that applies to any schema or sub-schema based on the schema's $id value. This is useful when your custom field should be conditionally applied based on the schema rather than the property name or data type.

To provide a custom field in this way, the fields prop should be an object which contains a key that matches the $id value of the schema which should have a custom field; here's an example:

import { RJSFSchema, FieldProps, RegistryFieldsType } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const CustomIdField = function (props: FieldProps) {
  return (
    <div id='custom'>
      <p>Yeah, I'm pretty dumb.</p>
      <div>My props are: {JSON.stringify(props)}</div>
    </div>
  );
};

const fields: RegistryFieldsType = {
  '/schemas/my-id': CustomIdField,
};

const schema: RJSFSchema = {
  $id: '/schemas/my-id',
  type: 'string',
};

render(<Form schema={schema} validator={validator} fields={fields} />, document.getElementById('app'));

Wrapping an existing field to customize it Copy Section

Sometimes you just need to customize the properties that are passed to an existing field.

Here is an example of wrapping the ObjectField to tweak the onChange handler to look for a specific kind of bad data:

import { useCallback } from 'react';
import { FieldProps } from '@rjsf/utils';
import { getDefaultRegistry } from '@rjsf/core';

import checkBadData from './checkBadData';

const {
  fields: { ObjectField },
} = getDefaultRegistry();

function MyObjectField(props: FieldProps) {
  const { onChange } = props;
  const onChangeHandler = useCallback(
    (newFormData: T | undefined, path: (number | string)[], es?: ErrorSchema<T>, id?: string) => {
      let data = newFormData;
      let error = es;
      if (checkBadData(newFormData)) {
        // Format the `error` and fix the `data` here
      }
      onChange(data, path, error, id);
    },
    [onChange],
  );
  return <ObjectField {...props} onChange={onChangeHandler} />;
}

Packages Docs Docs Advanced Customization Internals (`packages/docs/docs/advanced-customization/internals.md`) Copy Section

Internals

Miscellaneous internals of react-jsonschema-form are listed here.

JSON Schema supporting status Copy Chapter

This component follows JSON Schema specs. We currently support JSON Schema-07 by default, but we also support other JSON schema versions through the custom schema validation feature. Due to the limitation of form widgets, there are some exceptions as follows:

• additionalItems keyword for arrays

  This keyword works when items is an array. additionalItems: true is not supported because there's no widget to represent an item of any type. In this case it will be treated as no additional items allowed. additionalItems being a valid schema is supported.

• anyOf, allOf, and oneOf, or multiple types (i.e. "type": ["string", "array"])

  The anyOf and oneOf keywords are supported; however, properties declared inside the anyOf/oneOf should not overlap with properties "outside" of the anyOf/oneOf.

  You can also use oneOf with schema dependencies to dynamically add schema properties based on input data.

  The allOf keyword is supported; it uses @x0k/json-schema-merge to merge subschemas to render the final combined schema in the form. When these subschemas are incompatible, though (or if the library has an error merging it), the allOf keyword is dropped from the schema.

• "additionalProperties":false produces incorrect schemas when used with schema dependencies. This library does not remove extra properties, which causes validation to fail. It is recommended to avoid setting "additionalProperties":false when you use schema dependencies. See #848 #902 #992

Handling of schema defaults Copy Chapter

This library automatically fills default values defined in the JSON Schema as initial values in your form. This also works for complex structures in the schema. If a field has a default defined, it should always appear as default value in form. This also works when using schema dependencies.

Since there is a complex interaction between any supplied original form data and any injected defaults, this library tries to do the injection in a way which keeps the original intention of the original form data.

Check out the defaults example on the live playground to see this in action.

Merging of defaults into the form data Copy Section

There are three different cases which need to be considered for the merging. Objects, arrays and scalar values. This library always deeply merges any defaults with the existing form data for objects.

This are the rules which are used when injecting the defaults:

• When there is a scalar in the form data, nothing is changed.
• When the value is undefined in the form data, the default is created in the form data.
• When the value is an object in the form data, the defaults are deeply merged into the form data, using the rules defined here for the deep merge.
• Then the value is an array in the form data, defaults are only injected in existing array items. No new array items will be created, even if the schema has minItems or additional items defined.

A boolean property that is listed in its parent's required array and has no default of its own is populated with false. You can turn this off using the experimental requiredBooleanDefault flag, so that the property stays undefined until the user answers it.

Merging of defaults within the schema Copy Section

In the schema itself, defaults of parent elements are propagated into children. So when you have a schema which defines a deeply nested object as default, these defaults will be applied to children of the current node. This also merges objects defined at different levels together, with the deeper (descendant) default taking precedence for any overlapping properties by default. You can change this behavior using the experimental nestedDefaultsPrecedence flag. If the parent node defines properties which are not defined in the child, they will be merged so that the default for the child will be the merged defaults of parent and child.

For arrays this is not the case. Defining an array, when a parent also defines an array, will be overwritten. This is only true when arrays are used in the same level, for objects within these arrays, they will be deeply merged again.

Custom array field buttons Copy Chapter

The ArrayField component provides a UI to add, copy, remove and reorder array items, and these buttons use Bootstrap glyphicons.
If you don't use glyphicons but still want to provide your own icons or texts for these buttons, you can easily do so using CSS:

NOTE this only applies to the @rjsf/core theme

i.glyphicon {
  display: none;
}
.btn-add::after {
  content: 'Add';
}
.array-item-copy::after {
  content: 'Copy';
}
.array-item-move-up::after {
  content: 'Move Up';
}
.array-item-move-down::after {
  content: 'Move Down';
}
.array-item-remove::after {
  content: 'Remove';
}

Submit form programmatically Copy Chapter

You can use the reference to get your Form component and call the submit method to submit the form programmatically without a submit button.
This method will dispatch the submit event of the form, and the function, that is passed to onSubmit props, will be called.

import { createRef } from 'react';
import { RJSFSchema, UiSchema } from '@rjsf/utils';
import { Form } from '@rjsf/core';
import validator from '@rjsf/validator-ajv8';

const onSubmit = ({ formData }) => console.log('Data submitted: ', formData);
let yourForm;

const schema: RJSFSchema = {
  type: 'string',
};

const formRef = createRef<Form>();

render(
  <Form schema={schema} validator={validator} onSubmit={onSubmit} ref={formRef} />,
  document.getElementById('app'),
);

formRef.current.submit();

Update field value in form programmatically Copy Chapter

You can use the reference to get your Form component and call the setFieldValue(fieldPath: string | FieldPathList, newValue?: T): void method to change the value of a field.
This method will dispatch the onChange event of the form.

import { createRef } from 'react';
import { RJSFSchema, UiSchema } from '@rjsf/utils';
import { Form } from '@rjsf/core';
import validator from '@rjsf/validator-ajv8';

const onChange = ({ formData }) => console.log('Data updated to: ', formData);
let yourForm;

const schema: RJSFSchema = {
  type: 'object',
  properties: {
    foo: {
      type: 'object',
      required: ['input'],
      properties: {
        input: {
          type: 'string',
        },
      },
    },
  },
  required: ['foo'],
};

const formRef = createRef<Form>();

render(
  <Form schema={schema} validator={validator} onSubmit={onSubmit} ref={formRef} />,
  document.getElementById('app'),
);

formRef.current.setFieldValue('foo.input', 'value');
formRef.current.setFieldValue(['foo'], { input: 'newvalue' });
formRef.current.setFieldValue('', { foo: { input: 'another value' } });
formRef.current.setFieldValue([], { foo: { input: 'more values' } });

Packages Docs Docs Advanced Customization Typescript (`packages/docs/docs/advanced-customization/typescript.md`) Copy Section

Typescript Support

RJSF fully supports Typescript.
The types and functions exported by @rjsf/utils are fully typed (as needed) using one or more of the following 3 optional generics:

• T = any: This represents the type of the formData and defaults to any.
• S extends StrictRJSFSchema = RJSFSchema: This represents the type of the schema and extends the StrictRJSFSchema type and defaults to the RJSFSchema type.
• F extends FormContextType = any: This represents the type of the formContext, extends the FormContextType type and defaults to any.

Every other library in the @rjsf/* ecosystem use these same generics in their functions and React component definitions.
For instance, in the @rjsf/core library the definitions of the Form component and the withTheme() and getDefaultRegistry() functions are as follows:

export default class Form<
  T = any,
  S extends StrictRJSFSchema = RJSFSchema,
  F extends FormContextType = any
> extends Component<FormProps<T, S, F>, FormState<T, S, F>> {
  // ... class implementation
}

export default function withTheme<T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>(
  themeProps: ThemeProps<T, S, F>
) {
  // ... function implementation
}

export default function getDefaultRegistry<
  T = any,
  S extends StrictRJSFSchema = RJSFSchema,
  F extends FormContextType = any
>(): Omit<Registry<T, S, F>, 'schemaUtils'> {
  // ... function implementation
}

Out of the box, the defaults for these generics will work for all use-cases.
Providing custom types for any of these generics may be useful for situations where the caller is working with typed formData, schema or formContext props, Typescript is complaining and type casting isn't allowed.

Overriding generics Copy Chapter

T Copy Section

The generic T is used to represent the type of the formData property passed into Form.
If you are working with a simple, unchanging JSON Schema and you have defined a type for the formData you are working with, you can override this generic as follows:

import { RJSFSchema } from '@rjsf/utils';
import { customizeValidator } from '@rjsf/validator-ajv8';
import { Form } from '@rjsf/core';

interface FormData {
  foo?: string;
  bar?: number;
}

const schema: RJSFSchema = {
  type: 'object',
  properties: {
    foo: { type: 'string' },
    bar: { type: 'number' },
  },
};

const formData: FormData = {};

const validator = customizeValidator<FormData>();

render(<Form<FormData> schema={schema} validator={validator} formData={formData} />, document.getElementById('app'));

S Copy Section

The generic S is used to represent the type of the schema property passed into Form.
If you are using something like the Ajv utility types for schemas typing system, you can override this generic as follows:

import { JSONSchemaType } from 'ajv';
import { RJSFSchema } from '@rjsf/utils';
import { customizeValidator } from '@rjsf/validator-ajv8';
import { Form } from '@rjsf/core';

interface FormData {
  foo?: string;
  bar?: number;
}

type MySchema = JSONSchemaType<FormData>;

const schema: MySchema = {
  type: 'object',
  properties: {
    foo: { type: 'string' },
    bar: { type: 'number' },
  },
};

const validator = customizeValidator<any, MySchema>();

render(<Form<any, MySchema> schema={schema} validator={validator} />, document.getElementById('app'));

// Alternatively since you have the type, you could also use this
// const validator = customizeValidator<FormData, MySchema>();
// render((
//  <Form<FormData, MySchema> schema={schema} validator={validator} />
//), document.getElementById("app"));

NOTE: using this Ajv typing system has not been tested extensively with RJSF, so use carefully

F Copy Section

The generic F is used to represent the type of the formContext property passed into Form.
If you have a type for this data, you can override this generic as follows:

import { RJSFSchema } from '@rjsf/utils';
import { customizeValidator } from '@rjsf/validator-ajv8';
import { Form } from '@rjsf/core';

interface FormContext {
  myCustomWidgetData: object;
}

const schema: RJSFSchema = {
  type: 'object',
  properties: {
    foo: { type: 'string' },
    bar: { type: 'number' },
  },
};

const formContext: FormContext = {
  myCustomWidgetData: {
    enableCustomFeature: true,
  },
};

const validator = customizeValidator<any, RJSFSchema, FormContext>();

render(
  <Form<any, RJSFSchema, FormContext> schema={schema} validator={validator} formContext={formContext} />,
  document.getElementById('app')
);

Overriding generics in core Copy Chapter

As shown in previous examples, overriding the default Form from @rjsf/core is pretty straight forward.
Using the withTheme() function is just as easy:

import { RJSFSchema } from '@rjsf/utils';
import { customizeValidator } from '@rjsf/validator-ajv8';
import { withTheme, ThemeProps } from '@rjsf/core';

interface FormData {
  foo?: string;
  bar?: number;
}

type MySchema = JSONSchemaType<FormData>;

const schema: MySchema = {
  type: 'object',
  properties: {
    foo: { type: 'string' },
    bar: { type: 'number' },
  },
};

interface FormContext {
  myCustomWidgetData: object;
}

const theme: ThemeProps<FormData, MySchema, FormContext> = {
  widgets: { test: () => <div>test</div> },
};

const ThemedForm = withTheme<FormData, MySchema, FormContext>(theme);

const validator = customizeValidator<FormData, MySchema, FormContext>();

const Demo = () => <ThemedForm schema={schema} uiSchema={uiSchema} validator={validator} />;

Overriding generics in other themes Copy Chapter

Since all the other themes in RJSF are extensions of @rjsf/core, overriding parts of these themes with custom generics is a little different.
The exported Theme and Form from any of the themes have been created using the generic defaults, and as a result, do not take generics themselves.
In order to override generics, special generateForm() and generateTheme() functions are exported for your use.

Overriding a Theme Copy Section

If you are doing something like the following to create a new theme based on @rjsf/mui to extend one or more templates:

import React from 'react';
import { WidgetProps } from '@rjsf/utils';
import { ThemeProps, withTheme } from '@rjsf/core';
import validator from '@rjsf/validator-ajv8';
import { Theme } from '@rjsf/mui';

const OldBaseInputTemplate = Theme.templates.BaseInputTemplate;

// Force the underlying `TextField` component to always use size="small"
function MyBaseInputTemplate(props: WidgetProps) {
  return <OldBaseInputTemplate {...props} size='small' />;
}

const myTheme: ThemeProps = {
  ...Theme,
  templates: {
    ...Theme.templates,
    BaseInputTemplate: MyBaseInputTemplate,
  },
};

const ThemedForm = withTheme(myTheme);

const Demo = () => <ThemedForm schema={schema} uiSchema={uiSchema} validator={validator} />;

Then you would use the new generateTheme() and generateForm() functions as follows:

import React from 'react';
import { WidgetProps } from '@rjsf/utils';
import { ThemeProps, withTheme } from '@rjsf/core';
import { customizeValidator } from '@rjsf/validator-ajv8';
import { generateTheme } from '@rjsf/mui';

interface FormData {
  foo?: string;
  bar?: number;
}

type MySchema = JSONSchemaType<FormData>;

const schema: MySchema = {
  type: 'object',
  properties: {
    foo: { type: 'string' },
    bar: { type: 'number' },
  },
};

interface FormContext {
  myCustomWidgetData: object;
}

const Theme: ThemeProps<FormData, MySchema, FormContext> = generateTheme<FormData, MySchema, FormContext>();

const OldBaseInputTemplate = Theme.templates.BaseInputTemplate;

// Force the underlying `TextField` component to always use size="small"
function MyBaseInputTemplate(props: WidgetProps<FormData, MySchema, FormContext>) {
  return <OldBaseInputTemplate {...props} size='small' />;
}

const myTheme: ThemeProps<FormData, MySchema, FormContext> = {
  ...Theme,
  templates: {
    ...Theme.templates,
    BaseInputTemplate: MyBaseInputTemplate,
  },
};

const ThemedForm = withTheme<FormData, MySchema, FormContext>(myTheme);

const validator = customizeValidator<FormData, MySchema, FormContext>();

// You could also do since they are effectively the same:
// const ThemedForm = generateForm<FormData, MySchema, FormContext>(myTheme);

const Demo = () => <ThemedForm schema={schema} uiSchema={uiSchema} validator={validator} />;

NOTE: The same approach works for extending widgets and fields as well.

Packages Docs Docs Api Reference LayoutGridField (`packages/docs/docs/api-reference/LayoutGridField.md`) Copy Section

LayoutGridField

The LayoutGridField will render a schema, uiSchema and formData combination out into a GridTemplate in the shape
described in the uiSchema. To define the grid to use to render the elements within a field in the schema, provide in
the uiSchema for that field the object contained under a ui:layoutGrid element. E.g. (as a JSON object):

{
  "field1" : {
    "ui:field": "LayoutGridField",
    "ui:layoutGrid": {
      "ui:row": { ... }
    }
  }
}

See the LayoutGridField usage for more detailed walk-through on how to use the component. This page is condensed
version of the uiSchema APIs for faster reference.

`ui:row` Copy Chapter

The outermost level of a LayoutGridField is the ui:row that defines the nested rows, columns, and/or condition
elements (i.e. "grid elements") in the grid. This definition is either a simple "grid elements" OR an object with
native GridTemplate implementation-specific props and a children array of "grid elements". E.g. (as JSON objects):

Simple ui:row definition, without additional GridTemplate props:

{
  "ui:row": [
    { "ui:row"|"ui:col"|"ui:columns"|"ui:condition": ... },
    ...
  ]
}

Complex ui:row definition, with additional GridTemplate (this example uses @mui/material/Grid2 native props):

{
  "ui:row": {
    "spacing": 2,
    "size": {
      "md": 4
    },
    "alignContent": "flex-start",
    "className": "GridRow",
    "children": [
        {
          "ui:row"|"ui:col"|"ui:columns"|"ui:condition": ...
        },
        ...
      ]
    }
  }

NOTE: Special note about the native className prop values. All className values will automatically be looked up in
the formContext.lookupMap in case they have been defined using a CSS-in-JS approach. In other words, from the
example above, if the Form was constructed with a layoutGridLookupMap set to { GridRow: cssInJs.GridRowClass }
then when rendered, the native GridTemplate will get the className with the value from
cssInJs.GridRowClass. This automatic lookup will happen for any of the "grid elements" when rendering with
GridTemplate props. If multiple className values are present, for example:
{ className: 'GridRow GridColumn' }, the classNames are split apart, looked up individually, and joined
together to form one className with the values from cssInJs.GridRowClass and cssInJs.GridColumnClass. See the
example in the usage documentation.

`ui:col` Copy Chapter

The ui:col grid element is used to specify the list of columns within a grid row. A ui:col element can take on
several forms:

1. a simple list of dotted-path field names within the root field;
2. a list of objects containing the dotted-path field name any other props that are gathered into ui:options for the field;
3. a list with a one-off render functional component with or without a non-field name identifier and any other to-be-spread props; and
4. an object with native GridTemplate implementation specific props and a children array with 1) or 2) or even a nested ui:row or a ui:condition containing a ui:row (although this should be used carefully). E.g. (as JSON objects):

Simple ui:col definition, without additional GridTemplate props and form 1 only children:

{
  "ui:col": ["innerField", "inner.grandChild", ...]
}

Complicated ui:col definition, without additional GridTemplate props and form 2 only children:

{
  "ui:col": [
    { "name": "innerField", "fullWidth": true },
    { "name": "inner.grandChild", "fullWidth": false },
    ...
  ]
}

More complicated ui:col definition, without additional GridTemplate props and form 2 children, one being a
one-off render functional component without a non-field name identifier

{
  "ui:col": [
    "innerField",
    {
      "render": "WizardNavButton",
      "isNext": true,
      "size": "large"
    }
  ]
}

Most complicated ui:col definition, additional GridTemplate props and form 1, 2 and 3 children (this example
uses @mui/material/Grid2 native props):

{
  "ui:col": {
    "size": { "md": 4 },
    "className": "GridColumn",
    "children": [
      "innerField",
      { "name": "inner.grandChild", "fullWidth": true },
      { "name": "customRender", "render": "CustomRender", "toSpread": "prop-value" },
      { "ui:row|ui:condition": ... },
      ...
    ]
  }
}

NOTE: If a name prop does not exist or its value does not match any field in a schema, then it is assumed to be a
custom render component. If the render prop does not exist, a null render will occur. If render is a
string, its value will be looked up in the formContext.lookupMap first before defaulting to a null render. If the
resulting looked up render is not a function (React components are functions), then it will be a null render.

`ui:columns` Copy Chapter

The ui:columns grid element is syntactic sugar to specify a set of ui:col columns that all share the same set of
native GridTemplate props. In other words rather than writing the following configuration that renders a
<GridTemplate> element with 3 <GridTemplate column className="GridColumn col-md-4"> nodes and 2
<GridTemplate column className="col-md-6"> nodes within it (one for each of the fields contained in the children
list):

{
  "ui:row": {
    "children": [
      {
        "ui:col": {
          "className": "GridColumn col-md-4",
          "children": ["innerField"]
        }
      },
      {
        "ui:col": {
          "className": "GridColumn col-md-4",
          "children": ["inner.grandChild"]
        }
      },
      {
        "ui:col": {
          "className": "GridColumn col-md-4",
          "children": [{ "name": "inner.grandChild2" }]
        }
      },
      {
        "ui:col": {
          "className": "col-md-6",
          "children": ["innerField2"]
        }
      },
      {
        "ui:col": {
          "className": "col-md-6",
          "children": ["inner.grandChild3"]
        }
      }
    ]
  }
}

One can write this instead:

{
  "ui:row": {
    "children": [
      {
        "ui:columns": {
          "className": "GridColumn col-md-4",
          "children": ["innerField", "inner.grandChild", { "name": "inner.grandChild2", "fullWidth": true }]
        }
      },
      {
        "ui:columns": {
          "className": "col-md-6",
          "children": ["innerField2", "inner.grandChild3"]
        }
      }
    ]
  }
}

NOTE: This syntax differs from "ui:col": { "className": "col-md-6", "children": ["innerField2", "inner.grandChild3"] } in that
the ui:col will render the two children fields inside a single <GridTemplate "className": "col-md-6",>
element.

`ui:condition` Copy Chapter

The final grid element, ui:condition, allows for conditionally displaying "grid elements" within a row based on the
current value of a field as it relates to a (list of) hard-coded value(s). There are four elements that make up a
ui:condition:

1. the dotted-path field name within the root field that makes up the left-side of the condition;
2. the hard-coded value (single or list) that makes up the right-side of the condition;
3. the operator that controls how the left and right sides of the condition are compared; and
4. the children array that defines the "grid elements" to display if the condition passes.

A ui:condition uses one of three operators when deciding if a condition passes:

1. The all operator will pass when the right-side and left-side contains all the same value(s);
2. the some operator will pass when the right-side and left-side contain as least one value in common;
3. the none operator will pass when the right-side and left-side do not contain any values in common. E.g. (as JSON objects):

Here is how to render an if-then-else for field2 which is an enum that has 3 known values and supports allowing
any other value:

{
  "ui:row": [
    {
      "ui:condition": {
        "field": "field2",
        "operator": "all",
        "value": "value1",
        "children": [
          { "ui:row": [...] }
        ],
      }
    },
    {
      "ui:condition": {
        "field": "field2",
        "operator": "some",
        "value": ["value2", "value3"],
        "children": [
          { "ui:row": [...] }
        ],
      }
    },
    {
      "ui:condition": {
        "field": "field2",
        "operator": "none",
        "value": ["value1", "value2", "value3"],
        "children": [
          { "ui:row": [...] }
        ]
      }
    }
  ]
}

Packages Docs Docs Api Reference Dynamic Ui Schema Examples (`packages/docs/docs/api-reference/dynamic-ui-schema-examples.md`) Copy Section

Dynamic uiSchema Examples

Backward Compatibility Examples Copy Chapter

Example 1: Traditional Static uiSchema (No Changes Required) Copy Section

import { UiSchema } from '@rjsf/utils';

// This continues to work exactly as before
const uiSchema: UiSchema = {
  guests: {
    items: {
      name: { 'ui:placeholder': 'Enter guest name' },
      age: { 'ui:widget': 'updown' },
      relationship: { 'ui:widget': 'select' },
    },
  },
};

Example 2: Dynamic uiSchema with Function Copy Section

/* Detailed source-code truncated for AI context efficiency. */

Example 3: Using Form Context Copy Section

import { UiSchema, FormContextType } from '@rjsf/utils';

interface ParticipantData {
  name?: string;
  email?: string;
  workshop?: string;
}

interface MyFormContext extends FormContextType {
  eventType?: 'conference' | 'workshop' | 'webinar';
}

const uiSchema: UiSchema<any, any, MyFormContext> = {
  participants: {
    items: (itemData: ParticipantData | undefined, index: number, formContext?: MyFormContext): UiSchema => {
      // Access form-wide settings
      const isConference = formContext?.eventType === 'conference';

      return {
        name: { 'ui:placeholder': 'Participant name' },
        email: { 'ui:widget': 'email' },
        // Show workshop selection only for conference events
        workshop: isConference ? { 'ui:widget': 'select' } : { 'ui:widget': 'hidden' },
      };
    },
  },
};

Example 4: Falsy Return Values Copy Section

import { UiSchema, FormContextType } from '@rjsf/utils';

interface ItemData {
  needsCustomUI?: boolean;
  field1?: string;
  field2?: string;
}

const uiSchema: UiSchema = {
  items: {
    items: (itemData: ItemData | undefined, index: number): UiSchema | null | undefined => {
      // Only apply custom UI to specific items
      if (itemData?.needsCustomUI) {
        return {
          field1: { 'ui:widget': 'textarea' },
          field2: { 'ui:help': 'This item needs special attention' },
        };
      }

      // Return null or undefined to use default UI rendering
      // This is useful for conditionally applying custom UI
      return null;
    },
  },
};

Example 5: Dynamic UI for Fixed Arrays Copy Section

For fixed/tuple arrays (where schema.items is an array), the dynamic function can be applied to each position:

import { RJSFSchema, UiSchema } from '@rjsf/utils';

interface DetailsData {
  age?: number;
  role?: string;
}

const schema: RJSFSchema = {
  type: 'array',
  items: [
    { type: 'string', title: 'First Name' },
    { type: 'string', title: 'Last Name' },
    { type: 'object', title: 'Details', properties: { age: { type: 'number' }, role: { type: 'string' } } },
  ],
};

const uiSchema: UiSchema = {
  items: [
    { 'ui:placeholder': 'Enter first name' }, // Static UI for first item
    { 'ui:placeholder': 'Enter last name' }, // Static UI for second item
    // Dynamic UI for third item based on its data
    (itemData: DetailsData | undefined, index: number): UiSchema => {
      if (itemData?.role === 'admin') {
        return {
          age: { 'ui:widget': 'hidden' },
          role: { 'ui:help': 'Admin role selected' },
        };
      }
      return {
        age: { 'ui:widget': 'updown' },
        role: { 'ui:widget': 'select' },
      };
    },
  ],
};

Schema Example Copy Chapter

import { RJSFSchema } from '@rjsf/utils';

const schema: RJSFSchema = {
  type: 'object',
  properties: {
    guests: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          name: { type: 'string', title: 'Name' },
          age: { type: 'number', title: 'Age' },
          relationship: {
            type: 'string',
            title: 'Relationship',
            enum: ['adult', 'child', 'senior'],
          },
          guardianName: { type: 'string', title: 'Guardian Name' },
          mealPreference: {
            type: 'string',
            title: 'Meal Preference',
            enum: ['vegetarian', 'vegan', 'standard', 'gluten-free'],
          },
        },
        required: ['name', 'relationship'],
      },
    },
  },
};

Key Benefits Copy Chapter

1. Backward Compatible: Existing forms with object-based uiSchema.items continue to work without any changes
2. Progressive Enhancement: Developers can opt-in to dynamic behavior when needed
3. Flexible: Access to item data, index, and form context enables complex UI logic
4. Safe: Built-in error handling prevents the entire form from crashing if your function throws an error. When an error occurs for a specific item, it will be caught and logged to the developer console, and the UI for that item will fall back to the default rendering. This ensures the rest of the form remains functional while making debugging easier.
5. On-Demand Execution: The function is executed on-demand during the render cycle. However, as it runs for each array item, performance should be carefully managed for large lists (see Performance Considerations below).

Key Behaviors Copy Chapter

• Falsy Returns: If your function returns a falsy value (e.g., null or undefined), the UI for that specific item will fall back to its default rendering. This allows you to conditionally apply custom UI only when needed.
• Error Handling: If your function throws an error, it will be caught and logged to the console. The form will continue to work, using default UI for the affected item.
• New Items: When a new item is added to the array, itemData will be undefined or contain default values from the schema. Always use optional chaining (?.) to safely access properties.

Performance Considerations Copy Chapter

When using dynamic uiSchema.items functions, keep in mind:

• The function is executed on every render for each array item
• For large arrays, this can impact performance if the function performs expensive operations
• Best practices:
  • Keep the function logic lightweight and fast
  • Avoid heavy computations or external API calls within the function
  • Consider memoizing results if the same inputs produce the same outputs
  • For complex logic, pre-compute values and store them in formContext or component state

Example of a performance-optimized approach:

import React, { PropsWithChildren, useMemo } from 'react';
import Form from '@rjsf/core';
import { RJSFSchema, UiSchema, FormContextType, IChangeEvent } from '@rjsf/utils';

interface ItemData {
  type?: string;
  field?: any;
}

interface ExpensiveDataConfig {
  widget: string;
}

interface MyFormProps {
  schema: RJSFSchema;
  formData?: any;
}

// In your React component that renders the form:
function MyFormComponent({ schema, formData }: PropsWithChildren<MyFormProps>) {
  // Pre-compute expensive data once, and only re-compute if dependencies change
  const expensiveData = useMemo<Record<string, ExpensiveDataConfig>>(() => computeExpensiveData(), [/* dependencies */]);

  const defaultConfig: ExpensiveDataConfig = { widget: 'text' };

  // Define the uiSchema inside the component so it can access the memoized data
  const uiSchema: UiSchema = {
    myArrayField: { // Target your specific array field
      items: (itemData: ItemData | undefined, index: number, formContext?: FormContextType): UiSchema => {
        // Use the pre-computed data - this is very fast
        const config = expensiveData[itemData?.type || ''] || defaultConfig;

        return {
          field: { 'ui:widget': config.widget }
        };
      }
    }
  };

  return <Form schema={schema} uiSchema={uiSchema} formData={formData} />;
}

// Placeholder for the expensive computation function
declare function computeExpensiveData(): Record<string, ExpensiveDataConfig>;

Packages Docs Docs Api Reference Form Props (`packages/docs/docs/api-reference/form-props.md`) Copy Section

title:

Props Copy Chapter

<Form /> props

acceptCharset Copy Chapter

The value of this prop will be passed to the accept-charset HTML attribute on the form.

action Copy Chapter

The value of this prop will be passed to the action HTML attribute on the form.

Note that this just renders the action attribute in the HTML markup. There is no real network request being sent to this action on submit. Instead, react-jsonschema-form catches the submit event with event.preventDefault() and then calls the onSubmit function, where you could send a request programmatically with fetch or similar.

autoComplete Copy Chapter

The value of this prop will be passed to the autocomplete HTML attribute on the form.

className Copy Chapter

The value of this prop will be passed to the class HTML attribute on the form.

children Copy Chapter

You can provide custom buttons to your form via the Form component's children. If no children are provided, by default a Submit button will be rendered.

For other ways to modify the default Submit button, see both the Submit Button Options and the SubmitButton Template documentation.

import { Form } from '@rjsf/core';
import { RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
};

render(
  <Form schema={schema} validator={validator}>
    <div>
      <button type='submit'>Submit</button>
      <button type='button'>Cancel</button>
    </div>
  </Form>,
  document.getElementById('app'),
);

Warning: There needs to be a button or an input with type="submit" to trigger the form submission (and then the form validation).

customValidate Copy Chapter

Formerly the validate prop.
The customValidate prop requires a function that specifies custom validation rules for the form.
See Validation for more information.

experimental_componentUpdateStrategy Copy Chapter

Experimental feature to specify an alternative component update strategy that accepts one of the following value:
React's default Component rendering strategy is to re-render on every state change, see shouldComponentUpdate docs.
PureComponent's strategy uses shallow equality. One can also always update (not recommended for performance reasons, but can be useful for testing)

experimental_defaultFormStateBehavior Copy Chapter

Experimental features to specify different form state behavior.
Currently, this only affects the handling of optional array fields where minItems is set and handling of setting defaults based on the value of emptyObjectFields.

Warning: This API is experimental and unstable, therefore breaking changes may be shipped in minor or patch releases. If you want to use this feature, we recommend pinning exact versions of @rjsf/\* packages in your package.json file or be ready to update your use of it when necessary.

The following subsections represent the different keys in this object, with the tables explaining the values and their meanings.

arrayMinItems Copy Section

This optional subsection is an object with two optional fields, populate and mergeExtraDefaults.
When not specified, it defaults to { populate: 'all', mergeExtraDefaults: false }.

arrayMinItems.populate

Optional enumerated flag controlling how array minItems are populated, defaulting to all:

arrayMinItems.computeSkipPopulate

The signature and documentation for this property is as follow:

computeSkipPopulate <T = any, S extends StrictRJSFSchema = RJSFSchema, F extends FormContextType = any>()

A function that determines whether to skip populating the array with default values based on the provided validator, schema, and root schema.
If the function returns true, the array will not be populated with default values.
If the function returns false, the array will be populated with default values according to the populate option.

Parameters

• validator: ValidatorType<T, S, F> - An implementation of the ValidatorType interface that is used to detect valid schema conditions
• schema: S - The schema for which resolving a condition is desired
• [rootSchema]: S - The root schema that will be forwarded to all the APIs

Returns

• boolean: A boolean indicating whether to skip populating the array with default values.

Example

import { RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'object',
  properties: {
    stringArray: {
      type: 'array',
      items: { type: 'string' },
      minItems: 1,
    },
    numberArray: {
      type: 'array',
      items: { type: 'number' },
      minItems: 1,
    },
  },
  required: ['stringArray', 'numberArray'],
};

const computeSkipPopulateNumberArrays = (validator, schema, rootSchema) =>
  // These conditions are needed to narrow down the type of the schema.items
  !Array.isArray(schema?.items) &&
  typeof schema?.items !== 'boolean' &&
  schema?.items?.type === 'number',

render(
  <Form
    schema={schema}
    validator={validator}
    experimental_defaultFormStateBehavior={{
      arrayMinItems: {
        computeSkipPopulate: computeSkipPopulateNumberArrays,
      },
    }}
  />,
  document.getElementById('app')
);

arrayMinItems.mergeExtraDefaults

Optional boolean flag, defaulting to false when not specified.
When formData is provided and does not contain minItems worth of data, this flag controls whether the extra data provided by the defaults is appended onto the existing formData items to ensure the minItems condition is met.
When false (legacy behavior), only the formData provided is merged into the default form state, even if there are fewer than the minItems.
When true, the defaults are appended onto the end of the formData until the minItems condition is met.

emptyObjectFields Copy Section

Optional enumerated flag controlling how empty object fields are populated, defaulting to populateAllDefaults:

import { Form } from '@rjsf/core';
import { RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'array',
  items: { type: 'string' },
  minItems: 3,
};

render(
  <Form
    schema={schema}
    validator={validator}
    experimental_defaultFormStateBehavior={{
      emptyObjectFields: 'populateRequiredDefaults',
    }}
  />,
  document.getElementById('app'),
);

allOf Copy Section

Optional enumerated flag controlling how empty defaults are populated when allOf schemas are provided, defaulting to skipDefaults:

skipDefaults only skips the allOf schemas nested inside the schema that defaults are computed from, not that schema's own allOf.
Which schema that is depends on what the form is doing:

• When the form computes defaults from the root schema, a root-level allOf provides its defaults with either value.
• Some actions compute defaults from a subschema as if it were the root, such as adding an array item or optional data, or switching a oneOf or anyOf option, so that subschema's own allOf provides its defaults with either value. When switching options, though, the if of an if-then-else in the new option's allOf is checked against the data of the option being left, so under skipDefaults its then default is filled in only when that data matches the if.
• The option picked on the initial render is not computed as if it were the root, even when its oneOf or anyOf is in the root schema, so under skipDefaults its allOf is left out until the user switches away from that option and back.

The branch of an if-then-else is picked from the form data, not from the computed defaults, except in a dependencies entry, as the last item below says:

• When the if lists a property in required and only a default provides that property, the then default is left out until the form data holds the value, for instance on the initial render.
• Without required, a missing property still satisfies the if's properties, so such an if passes with no data, and its then default is filled in even when the if does not match the defaulted value.
• With one allOf entry per enum value and no form data, the default allOf merger merges the then defaults of all the entries, and the first entry that defaults a property wins. An experimental_customMergeAllOf that throws on the conflicting defaults drops the whole allOf instead.

An allOf in an object property or in an array's items is skipped as a whole, plain property defaults included, so it usually needs populateDefaults to provide its defaults.
This is specific to allOf:

• An if-then-else placed directly in a nested object schema is resolved with either value, unless emptyObjectFields is skipEmptyDefaults. For example, under skipDefaults, items: { type: 'object', if, then } fills in the then default, while items: { type: 'object', allOf: [{ if, then }] } does not.
• Adding a direct if to that items schema resolves its whole allOf too, unless emptyObjectFields is skipEmptyDefaults.
• With an experimental_customMergeAllOf built on a deep merger, such as createDeepAllOfMerge from @x0k/json-schema-merge given a shallow merge built with that library's createMerger and createShallowAllOfMerge, merging an allOf also turns a property's allOf: [{ if, then }] into a direct if-then-else, so that property's then default is filled in under skipDefaults, unless emptyObjectFields is skipEmptyDefaults. That happens wherever an allOf is merged: the root's own allOf, or the allOf of an object or items schema that also has a direct if, but not a nested allOf on its own.
• A dependencies entry in a nested object schema is resolved once its property has a value, its allOf and if-then-else included, even when emptyObjectFields is skipEmptyDefaults. A default counts as that value, and the entry's if is checked against it, so an if that lists the property in required passes with no form data, while one that does not match the default fails. For example, under skipDefaults, items: { type: 'object', properties: { animal: { default: 'Cat' } }, dependencies: { animal: { allOf: [{ if, then }] } } } fills in the then default. A root dependencies entry counts a default only while the form data is empty: once the form data holds any value, the entry is applied only when the form data holds its property.

import { Form } from '@rjsf/core';
import { RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  title: 'Example',
  type: 'object',
  properties: {
    animalInfo: {
      properties: {
        animal: {
          type: 'string',
          default: 'Cat',
          enum: ['Cat', 'Fish'],
        },
      },
      allOf: [
        {
          if: {
            properties: {
              animal: {
                const: 'Cat',
              },
            },
          },
          then: {
            properties: {
              food: {
                type: 'string',
                default: 'meat',
                enum: ['meat', 'grass', 'fish'],
              },
            },
            required: ['food'],
          },
        },
      ],
    },
  },
};

render(
  <Form
    schema={schema}
    validator={validator}
    experimental_defaultFormStateBehavior={{
      allOf: 'populateDefaults',
    }}
  />,
  document.getElementById('app'),
);

constAsDefaults Copy Section

Optional enumerated flag controlling how const values are merged into the form data as defaults when dealing with undefined values, defaulting to always.
The defaulting behavior for this flag will always be controlled by the emptyObjectField flag value.
For instance, if populateRequiredDefaults is set and the const value is not required, it will not be set.

mergeDefaultsIntoFormData Copy Section

Optional enumerated flag controlling how the defaults are merged into the form data when dealing with undefined values, defaulting to useFormDataIfPresent.

NOTE: If there is a default for a field and the formData is unspecified, the default ALWAYS merges.

nestedDefaultsPrecedence Copy Section

Optional enumerated flag controlling how defaults defined on multiple levels are merged together for overlapping properties, defaulting to descendantWins.

Example

In the following example, the animal property is a descendant of the root schema and both define a default value for animal. By default, the animal's default value Cat would take precedence over its ancestor's Fish. However, since nestedDefaultsPrecedence is set to ancestorWins, the root schema's default value takes precedence and animal is set to Fish by default.

import { Form } from '@rjsf/core';
import { RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'object',
  default: {
    animal: 'Fish',
  },
  properties: {
    animal: {
      type: 'string',
      default: 'Cat',
      enum: ['Cat', 'Fish'],
    },
  },
};

render(
  <Form
    schema={schema}
    validator={validator}
    experimental_defaultFormStateBehavior={{
      nestedDefaultsPrecedence: 'ancestorWins',
    }}
  />,
  document.getElementById('app'),
);

requiredBooleanDefault Copy Section

Optional enumerated flag controlling whether a boolean listed in its parent's required array, with no default of its own, is populated with false, defaulting to populateFalse.
An explicit schema default, a parent default and an existing formData value always take precedence; this flag only decides what happens when none of them provides a value.

Example

In the following example, agree is required but has no default. By default it would start as false, and the form would report { agree: false } through onChange on mount. With requiredBooleanDefault set to skip, formData stays {} until the user answers, and validation reports agree as missing until then. This is the behavior to choose when a boolean question is rendered with an explicit "unanswered" state, for example a - - - / Yes / No select, rather than a checkbox.

import { Form } from '@rjsf/core';
import { RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'object',
  properties: {
    agree: {
      type: 'boolean',
      title: 'Do you agree?',
    },
  },
  required: ['agree'],
};

render(
  <Form
    schema={schema}
    validator={validator}
    experimental_defaultFormStateBehavior={{
      requiredBooleanDefault: 'skip',
    }}
  />,
  document.getElementById('app'),
);

experimental_customMergeAllOf Copy Chapter

The experimental_customMergeAllOf function allows you to provide a custom implementation for merging allOf schemas. This can be particularly useful in case the where the default merge library (@x0k/json-schema-merge) doesn't satisfy your functional or performance requirements.

By providing your own implementation, you can potentially achieve significant performance improvements. For instance, if your use case only requires a subset of JSON Schema features, you can implement a faster, more tailored merging strategy.

If you're looking for alternative allOf merging implementations, you might consider allof-merge.

Warning: This is an experimental feature. Only use this if you fully understand the implications of custom allOf merging and are prepared to handle potential edge cases. Incorrect implementations may lead to unexpected behavior or validation errors.

import { Form } from '@rjsf/core';
import validator from '@rjsf/validator-ajv8';

const customMergeAllOf = (schema: RJSFSchema): RJSFSchema => {
  // Your custom implementation here
};

render(
  <Form schema={schema} validator={validator} experimental_customMergeAllOf={customMergeAllOf} />,
  document.getElementById('app'),
);

disabled Copy Chapter

It's possible to disable the whole form by setting the disabled prop. The disabled prop is then forwarded down to each field of the form.

import { Form } from '@rjsf/core';
import { RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
};

render(<Form schema={schema} validator={validator} disabled />, document.getElementById('app'));

If you just want to disable some fields, see the ui:disabled parameter in uiSchema.

readonly Copy Chapter

It's possible to make the whole form read-only by setting the readonly prop. The readonly prop is then forwarded down to each field of the form.

import { Form } from '@rjsf/core';
import { RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
};

render(<Form schema={schema} validator={validator} readonly />, document.getElementById('app'));

If you just want to make some fields read-only, see the ui:readonly parameter in uiSchema.

enctype Copy Chapter

The value of this prop will be passed to the enctype HTML attribute on the form.

extraErrors Copy Chapter

This prop allows passing in custom errors that are augmented with the existing JSON Schema errors on the form; it can be used to implement asynchronous validation.
By default, these are non-blocking errors, meaning that you can still submit the form when these are the only errors displayed to the user.
See Validation for more information.

extraErrorsBlockSubmit Copy Chapter

If set to true, causes the extraErrors to become blocking when the form is submitted.

fields Copy Chapter

Dictionary of registered fields in the form. See Custom Widgets and Fields for more information.

focusOnFirstError Copy Chapter

If set to true, then the first field with an error will receive the focus when the form is submitted with errors.

You can also provide a custom callback function to handle what happens when this function is called.

import { Form } from '@rjsf/core';
import { RJSFSchema, RJSFValidationError } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
};

const focusOnError = (error: RJSFValidationError) => {
  console.log('I need to handle focusing this error');
};

render(<Form schema={schema} validator={validator} focusOnFirstError={focusOnError} />, document.getElementById('app'));

formContext Copy Chapter

You can provide a formContext object to the Form, which is passed down to all fields and widgets. Useful for implementing context aware fields and widgets.

See AntD Customization for formContext customizations for the antd theme.
See Semantic UI Customization for formContext customizations for the semantic-ui theme.

formData Copy Chapter

The data for the form, used to load a "controlled" form with its current data. If you want an "uncontrolled" form with initial data, then use initialFormData instead.

id Copy Chapter

The value of this prop will be passed to the id HTML attribute on the form.

idPrefix Copy Chapter

To avoid collisions with existing ids in the DOM, it is possible to change the prefix used for ids (the default is root).

import { Form } from '@rjsf/core';
import { RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
};

render(<Form schema={schema} validator={validator} idPrefix={'rjsf_prefix'} />, document.getElementById('app'));

This will render instead of

idSeparator Copy Chapter

To avoid using a path separator that is present in field names, it is possible to change the separator used for ids (the default is _).

import { Form } from '@rjsf/core';
import { RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'object',
  properties: {
    first: {
      type: 'string',
    },
  },
};

render(<Form schema={schema} validator={validator} idSeparator={'/'} />, document.getElementById('app'));

This will render instead of when rendering first.

initialFormData Copy Chapter

The initial data for the form, used to fill an "uncontrolled" form with existing data on the initial render and when reset() is called programmatically.

nameGenerator Copy Chapter

The nameGenerator prop allows you to customize how HTML name attributes are generated for form fields. This is essential when submitting form data to backend frameworks that expect specific naming conventions for structured data.

Default behavior: When no nameGenerator is provided, the name attribute will equal the id attribute (e.g., root_tasks_0_title).

RJSF provides two built-in generators:

bracketNameGenerator - Generates bracket notation for PHP/Rails (e.g., root[tasks][0][title]). Automatically appends [] for multi-value fields like checkboxes.

dotNotationNameGenerator - Generates dot notation for other frameworks (e.g., root.tasks.0.title).

import { Form } from '@rjsf/core';
import { bracketNameGenerator, RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'object',
  properties: {
    firstName: { type: 'string' },
    tasks: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          title: { type: 'string' },
        },
      },
    },
  },
};

render(
  <Form schema={schema} validator={validator} nameGenerator={bracketNameGenerator} />,
  document.getElementById('app'),
);

You can also create a custom generator by implementing the NameGeneratorFunction type, which receives path (array of path segments), idPrefix (typically 'root'), and optional isMultiValue (boolean for multi-value fields).

liveOmit Copy Chapter

Flag that describes when live omit will be performed. Live omit happens only when omitExtraData is also set to
to true and the form's data is updated by the user.

If no value (or false) is provided, then live omit will not happen. If true or onChange is provided for
the flag, then live omit will be performed after processing of all pending changes has completed. If onBlur
is provided, then live omit will be performed when a field that was updated is blurred (as a performance
optimization).

NOTE: The boolean options for this flag is deprecated and will be removed in a future major release

liveValidate Copy Chapter

Flag that describes when live validation will be performed. Live validation means that the form will perform
validation and show any validation errors whenever the form data is updated, rather than just on submit.

If no value (or false) is provided, then live validation will not happen. If true or onChange is provided for
the flag, then live validation will be performed after processing of all pending changes has completed. If onBlur
is provided, then live validation will be performed when a field that was updated is blurred (as a performance
optimization).

NOTE: The boolean options for this flag is deprecated and will be removed in a future major release

method Copy Chapter

The value of this prop will be passed to the method HTML attribute on the form.

name Copy Chapter

The value of this prop will be passed to the name HTML attribute on the form.

noHtml5Validate Copy Chapter

If set to true, turns off HTML5 validation on the form. Set to false by default.

noValidate Copy Chapter

If set to true, turns off all validation. Set to false by default.

NOTE: In a future major release, this flag may be deleted replaced by making validator prop optional

omitExtraData Copy Chapter

If set to true, then extra form data values that are not in any form field will be removed whenever onSubmit is called. Set to false by default.

onBlur Copy Chapter

Sometimes you may want to trigger events or modify external state when a field has been touched, so you can pass an onBlur handler, which will receive the id of the input that was blurred and the field value.

onChange Copy Chapter

If you plan on being notified every time the form data are updated, you can pass an onChange handler, which will receive the same first argument as onSubmit any time a value is updated in the form.
It will also receive, as the second argument, the id of the field which experienced the change.
Generally, this will be the id of the field for which input data is modified.
In the case of adding/removing of new fields in arrays or objects with additionalProperties or patternProperties and the rearranging of items in arrays, the id will be that of the array or object itself, rather than the item/field being added, removed or moved.

onError Copy Chapter

To react when submitted form data are invalid, pass an onError handler. It will be passed the list of encountered errors:

import { Form } from '@rjsf/core';
import { RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
};
const onError = (errors) => console.log('I have', errors.length, 'errors to fix');

render(<Form schema={schema} validator={validator} onError={onError} />, document.getElementById('app'));

onFocus Copy Chapter

Sometimes you may want to trigger events or modify external state when a field has been focused, so you can pass an onFocus handler, which will receive the id of the input that is focused and the field value.

onSubmit Copy Chapter

You can pass a function as the onSubmit prop of your Form component to listen to when the form is submitted and its data are valid.
It will be passed a result object having a formData attribute, which is the valid form data you're usually after.
The original event will also be passed as a second parameter:

import { Form } from '@rjsf/core';
import { RJSFSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'string',
};
const onSubmit = ({ formData }, e) => console.log('Data submitted: ', formData);

render(<Form schema={schema} validator={validator} onSubmit={onSubmit} />, document.getElementById('app'));

Note: If there are fields in the formData that are not represented in the schema, they will be retained by default. If you would like to remove those extra values on form submission, you may need to set the omitExtraData and/or liveOmit props.

removeEmptyOptionalObjects Copy Chapter

Deprecated: This prop no longer has any effect and will be removed in a future release. The behavior of pruning optional empty objects is now built into omitExtraData — enable that prop instead.

When a JSON Schema has a required field inside an optional object, any user interaction with that optional object "activates" it. Even if the user clears all the fields within that object, the empty object property (e.g., { test: {} } or { test: { field1: "" } }) remains in the formData. Because the object contains required fields that are now empty, the form becomes unsubmittable.

Previously, setting removeEmptyOptionalObjects to true caused the form to recursively prune these optional empty objects from the formData during onChange, onBlur, and onSubmit. This pruning is now performed automatically by omitExtraData.

schema Copy Chapter

Required! Form schema. We support JSON schema draft-07 by default. See Schema Reference for more information.

showErrorList Copy Chapter

When this prop is set to top or bottom, a list of errors (or the custom error list defined in the ErrorList) will also show at the bottom or top of the form. When set to false, only inline input validation errors will be shown. Set to top by default. See Validation for more information.

tagName Copy Chapter

It's possible to change the default form tag name to a different HTML tag, which can be helpful if you are nesting forms. However, native browser form behaviour, such as submitting when the Enter key is pressed, may no longer work.

<Form
  tagName="div"
  ...
/>

You can also provide a class/function component.

const CustomForm = props => <form {...props} style={...} className={...} />
// ...
<Form
  tagName={CustomForm}
  ...
/>

target Copy Chapter

The value of this prop will be passed to the target HTML attribute on the form.

templates Copy Chapter

Dictionary of registered templates in the form. See Custom Templates for more information.

transformErrors Copy Chapter

A function can be passed to this prop in order to make modifications to the default errors resulting from JSON Schema validation. See Validation for more information.

translateString Copy Chapter

Optional string translation function, if provided, allows users to change the translation of the RJSF internal strings.
Some strings contain replaceable parameter values as indicated by %1, %2, etc.
The number after the % indicates the order of the parameter.
The ordering of parameters is important because some languages may choose to put the second parameter before the first in its translation. In addition to replaceable parameters, some of the strings support the use of markdown and simple html.

One can use the documentation of the TranslatableString enums to determine which enum values contain replaceable parameters and which support markdown and simple html.

One could use this function to alter one or more of the existing english strings to better suit one's application or fully translate all strings into a different language.
Below is an example of changing a few of the english strings to something else:

import { TranslatableString, englishStringTranslator, replaceStringParameters } from '@rjsf/utils';

function fixupSomeEnglishStrings(stringToTranslate: TranslatableString, params?: string[]): string {
  switch (stringToTranslate) {
    case TranslatableString.NewStringDefault:
      return ''; // Use an empty string for the new additionalProperties string default value
    case TranslatableString.KeyLabel:
      return replaceStringParameters('%1 Key Name', params); // Add "Name" onto the end of the WrapIfAdditionalTemplate key label
    default:
      return englishStringTranslator(stringToTranslate, params); // Fallback to the default english
  }
}

uiSchema Copy Chapter

Form uiSchema. See uiSchema Reference for more information.

useFallbackUiForUnsupportedType Copy Chapter

If set to true, when an unsupported schema type is encountered, the form will render a fallback UI instead of displaying an error. The fallback UI will display a widget that allows the user to select a JSON Schema primitive type, and a field containing the form data that matches the selected type. Set to false by default.

validator Copy Chapter

Required! An implementation of the ValidatorType interface that is needed for form validation to work.
@rjsf/validator-ajv8 exports the implementation of this interface from RJSF version 4.

widgets Copy Chapter

Dictionary of registered widgets in the form. See Custom Widgets and Fields for more information.

Packages Docs Docs Api Reference UiSchema (`packages/docs/docs/api-reference/uiSchema.md`) Copy Section

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 Copy Chapter

There are 4 properties that exist in a UiSchema that will not be found in an inner ui:options object.

`ui:globalOptions` Copy Section

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:definitions` Copy Section

The ui:definitions property allows you to define reusable UI customizations for schema $ref references. This is particularly useful for:

• Recursive schemas - Define uiSchema once for a self-referencing schema node
• Reused definitions - Apply consistent UI to schemas used in multiple places
• oneOf/anyOf branches - Provide different uiSchema for branches that reference different definitions

The keys in ui:definitions must match the exact $ref path used in the schema (e.g., #/definitions/address or #/$defs/node).

import { Form } from '@rjsf/core';
import { RJSFSchema, UiSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  definitions: {
    address: {
      type: 'object',
      properties: {
        street_address: { type: 'string' },
        city: { type: 'string' },
      },
    },
    node: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        children: {
          type: 'array',
          items: { $ref: '#/definitions/node' }, // Recursive reference
        },
      },
    },
  },
  type: 'object',
  properties: {
    billing_address: { $ref: '#/definitions/address' },
    shipping_address: { $ref: '#/definitions/address' },
    tree: { $ref: '#/definitions/node' },
  },
};

const uiSchema: UiSchema = {
  'ui:definitions': {
    '#/definitions/address': {
      street_address: { 'ui:placeholder': 'Street and number' },
      city: { 'ui:placeholder': 'City name' },
    },
    '#/definitions/node': {
      name: { 'ui:placeholder': 'Enter node name' },
      children: { 'ui:options': { orderable: false } },
    },
  },
  // Local overrides take precedence over ui:definitions
  shipping_address: {
    street_address: { 'ui:placeholder': 'Shipping street (overrides definition)' },
  },
};

render(<Form schema={schema} uiSchema={uiSchema} validator={validator} />, document.getElementById('app'));

Local Overrides

You can override specific properties from ui:definitions by providing values at the field path. Local values are merged with definitions, with local values taking precedence.

oneOf/anyOf with Same Property Names

When using oneOf or anyOf with branches that have properties with the same name, each branch's $ref maps to its own entry in ui:definitions, ensuring correct UI is applied:

const schema: RJSFSchema = {
  definitions: {
    person: { type: 'object', properties: { name: { type: 'string' } } },
    company: { type: 'object', properties: { name: { type: 'string' } } },
  },
  type: 'object',
  properties: {
    contact: {
      oneOf: [
        { title: 'Person', $ref: '#/definitions/person' },
        { title: 'Company', $ref: '#/definitions/company' },
      ],
    },
  },
};

const uiSchema: UiSchema = {
  'ui:definitions': {
    '#/definitions/person': {
      name: { 'ui:placeholder': 'Full name (e.g., John Doe)' },
    },
    '#/definitions/company': {
      name: { 'ui:placeholder': 'Company name (e.g., Acme Inc.)' },
    },
  },
};

`ui:rootFieldId` (deprecated) Copy Section

DEPRECATED: Use Form.idPrefix instead, 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` Copy Section

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` Copy Section

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` Copy Section

The ui:options property cannot be nested inside itself and thus is the last exception.

`ui:XXX` or `ui:options.XXX` Copy Chapter

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 Copy Section

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 Copy Section

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 Copy Section

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>

allowClearTextInputs Copy Section

The optional ui:allowClearTextInputs uiSchema directive enables a clear/reset button for text-based input widgets.
When set to true, a clear button will be displayed when the input field has a value and is not readonly or disabled.
When omitted, no clear button will be displayed for text input fields.

When clicked, the property value will be set to the ui:emptyValue, if defined.

import { RJSFSchema, UiSchema } from '@rjsf/utils';
const schema: RJSFSchema = { type: 'string' };
const uiSchema: UiSchema = {
  'ui:allowClearTextInputs': true,
};

It can also be enabled globally by setting the allowClearTextInputs option to true in the ui:globalOptions
uiSchema directive.

import { Form } from '@rjsf/core';
import { RJSFSchema, UiSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = { type: 'string' };
const uiSchema: UiSchema = {
  'ui:globalOptions': {
    allowClearTextInputs: true,
  },
};

autocomplete Copy Section

If you want to mark a text input, select or textarea input to use the HTML autocomplete feature, set the ui:autocomplete uiSchema directive to a valid HTML autocomplete value.

import { RJSFSchema, UiSchema } from '@rjsf/utils';

const schema: RJSFSchema = { type: 'string' };
const uiSchema: UiSchema = {
  'ui:widget': 'textarea',
  'ui:autocomplete': 'on',
};

autocapitalize Copy Section

To control automatic capitalization on virtual keyboards for a text input, set the ui:autocapitalize uiSchema
directive to a valid HTML autocapitalize value.

import { RJSFSchema, UiSchema } from '@rjsf/utils';

const schema: RJSFSchema = { type: 'string' };
const uiSchema: UiSchema = {
  'ui:autocapitalize': 'words',
};

autofocus Copy Section

If you want to automatically focus on a text input or textarea input, set the ui:autofocus uiSchema directive to true.

import { RJSFSchema, UiSchema } from '@rjsf/utils';

const schema: RJSFSchema = { type: 'string' };
const uiSchema: UiSchema = {
  'ui:widget': 'textarea',
  'ui:autofocus': true,
};

description Copy Section

Sometimes it's convenient to change the description of a field. This is the purpose of the ui:description uiSchema directive:

import { RJSFSchema, UiSchema } from '@rjsf/utils';

const schema: RJSFSchema = { type: 'string' };
const uiSchema: UiSchema = {
  'ui:widget': 'password',
  'ui:description': 'The best password',
};

deprecatedHandling Copy Section

The ui:deprecatedHandling uiSchema directive controls how a field marked as deprecated in the JSON Schema is rendered.

Accepts one of three values:

• 'label' (default): The field is rendered normally with "(deprecated)" appended to its label.
• 'disable': The field is rendered but all its child widgets are disabled.
• 'hide': The field is completely hidden from the form.

import { RJSFSchema, UiSchema } from '@rjsf/utils';

const schema: RJSFSchema = {
  type: 'object',
  properties: {
    legacyField: { type: 'string', deprecated: true },
  },
};

const uiSchema: UiSchema = {
  legacyField: {
    'ui:options': {
      deprecatedHandling: 'disable',
    },
  },
};

It can also be set globally by specifying the deprecatedHandling option in the ui:globalOptions uiSchema directive, which applies the chosen behavior to every deprecated field in the form.

import { Form } from '@rjsf/core';
import { RJSFSchema, UiSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = {
  type: 'object',
  properties: {
    legacyField: { type: 'string', deprecated: true },
    anotherOldField: { type: 'number', deprecated: true },
  },
};

const uiSchema: UiSchema = {
  'ui:globalOptions': {
    deprecatedHandling: 'hide',
  },
};

render(<Form schema={schema} uiSchema={uiSchema} validator={validator} />, document.getElementById('app'));

disabled Copy Section

The ui:disabled uiSchema directive will disable all child widgets from a given field.

Note: If you're wondering about the difference between a disabled field and a readonly one: Marking a field as read-only will render it greyed out, but its text value will be selectable. Disabling it will prevent its value to be selected at all.

enableMarkdownInDescription Copy Section

The ui:enableMarkdownInDescription uiSchema directive enables the support of Markdown syntax within the description of
a field.

import { Form } from '@rjsf/core';
import { RJSFSchema, UiSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = { type: 'string', description: '**bolded** text in the description' };
const uiSchema: UiSchema = {
  'ui:enableMarkdownInDescription': true,
};
render(<Form schema={schema} uiSchema={uiSchema} validator={validator} />, document.getElementById('app'));

It can also be enabled globally by setting the enableMarkdownInDescription option to true in the ui:globalOptions
uiSchema directive.

import { Form } from '@rjsf/core';
import { RJSFSchema, UiSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = { type: 'string', description: '**bolded** text in the description' };
const uiSchema: UiSchema = {
  'ui:globalOptions': {
    enableMarkdownInDescription: true,
  },
};

render(<Form schema={schema} uiSchema={uiSchema} validator={validator} />, document.getElementById('app'));

enableMarkdownInHelp Copy Section

The ui:enableMarkdownInHelp uiSchema directive enables the support of Markdown syntax within the help displayed for
a field.

import { Form } from '@rjsf/core';
import { RJSFSchema, UiSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = { type: 'string' };
const uiSchema: UiSchema = {
  'ui:enableMarkdownInHelp': true,
  'ui:help': '**bolded** text in the help',
};
render(<Form schema={schema} uiSchema={uiSchema} validator={validator} />, document.getElementById('app'));

It can also be enabled globally by setting the enableMarkdownInHelp option to true in the ui:globalOptions
uiSchema directive.

import { Form } from '@rjsf/core';
import { RJSFSchema, UiSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = { type: 'string' };
const uiSchema: UiSchema = {
  'ui:globalOptions': {
    enableMarkdownInHelp: true,
  },
  'ui:help': '**bolded** text in the help',
};

render(<Form schema={schema} uiSchema={uiSchema} validator={validator} />, document.getElementById('app'));

enableOptionalDataFieldForType Copy Section

The ui:enableOptionalDataFieldForType uiSchema directive enables support for displaying the Optional Data Controls feature.
The intention of this feature is to allow developers to provide a condensed UI for users who don't care to enter an optional list of array items or set of optional object fields (see examples below).

This directive takes, as its value, an array in one of four forms:

1. [] - Disables the feature at a global or field level
2. ['array'] - Enables the feature only for optional arrays at a global or field level
3. ['object'] - Enables the feature only for optional object at a global or field level
4. ['array', 'object']- Enables the feature for both optional object and arrays at a global or field level

It can be specified in either the ui:globalOptions to turn the feature on for everything or in a specific field's uiSchema
To work properly this option must be coupled with the emptyObjectFields experimental feature on Form using the populateRequiredDefaults or skipDefaults options.

When enabled for either (or both) the array or object types, any optional object or array field which has an "undefined" value in formData will NOT render any of the container's UI elements.
Instead the object/array container's field title will have an "Add optional data" icon button that, when clicked will cause an empty container data element to be added to formData.

When enabled for either (or both) the array or object types, any optional object or array field which has an "defined" value in formData will render all of the container's UI elements as normal AND the object/array container's field title will have a "Remove optional data" icon button that, when clicked will set the data for field in the formData to "undefined".

Here is an example of what the UI will look like when enabled using the following Form configuration:

const schema: RJSFSchema = {
  title: 'test',
  properties: {
    nestedObjectOptional: {
      type: 'object',
      properties: {
        test: {
          type: 'string',
        },
      },
    },
    nestedArrayOptional: {
      type: 'array',
      items: {
        type: 'string',
      },
    },
  },
};
const uiSchema = {
  'ui:globalOptions': {
    enableOptionalDataFieldForType: ['object', 'array'],
  },
};
const experimental_defaultFormStateBehavior = {
  // Set the emptyObjectFields to only populate required defaults to highlight the code working
  emptyObjectFields: 'populateRequiredDefaults',
};

render(
  <Form
    schema={schema}
    validator={validator}
    uiSchema={uiSchema}
    experimental_defaultFormStateBehavior={experimental_defaultFormStateBehavior}
    templates={{ OptionalDataControlsTemplate }}
  />,
  document.getElementById('app'),
);

Add Optional Data Controls

Remove Optional Data Controls

emptyValue Copy Section

The ui:emptyValue uiSchema directive provides the value to store when the input for a field is emptied, whether by typing or by clicking the ui:allowClearTextInputs clear button. It defaults to undefined, which omits the field from the form data entirely.

enumDisabled Copy Section

To disable an option, use the enumDisabled property in uiSchema.

import { RJSFSchema, UiSchema } from '@rjsf/utils';

const schema: RJSFSchema = {
  type: 'string',
  enum: ['one', 'two', 'three'],
};

const uiSchema: UiSchema = {
  'ui:enumDisabled': ['two'],
};

enumNames Copy Section

Allows a user to provide labels for enum values in the schema. Can be an array (matched by index) or a map (matched by value).

import { RJSFSchema, UiSchema } from '@rjsf/utils';

const schema: RJSFSchema = {
  type: 'number',
  enum: [1, 2, 3],
};

// Array form (matched by index)
const uiSchemaArray: UiSchema = {
  'ui:enumNames': ['one', 'two', 'three'],
};

// Map form (matched by value)
const uiSchemaMap: UiSchema = {
  'ui:enumNames': { 1: 'one', 2: 'two', 3: 'three' },
};

enumOrder Copy Section

Controls the display order of enum options. Use '*' to represent remaining values in their original schema order. Unlisted values not covered by '*' are dropped.

import { RJSFSchema, UiSchema } from '@rjsf/utils';

const schema: RJSFSchema = {
  type: 'string',
  enum: ['apple', 'banana', 'cherry', 'date'],
};

const uiSchema: UiSchema = {
  'ui:enumOrder': ['cherry', '*', 'apple'],
};

filePreview Copy Section

The FileWidget can be configured to show a preview of an image or a download link for non-images using this flag.

import { RJSFSchema, UiSchema } from '@rjsf/utils';

const schema: RJSFSchema = {
  type: 'string',
  format: 'data-url',
};
const uiSchema: UiSchema = {
  'ui:options': {
    filePreview: true,
  },
};

help Copy Section

Sometimes it's convenient to add text next to a field to guide the end user filling it. This is the purpose of the ui:help uiSchema directive:

import { RJSFSchema, UiSchema } from '@rjsf/utils';

const schema: RJSFSchema = { type: 'string' };
const uiSchema: UiSchema = {
  'ui:widget': 'password',
  'ui:help': 'Hint: Make it strong!',
};

Help texts work for any kind of field at any level, and will always be rendered immediately below the field component widget(s) (after contextualized errors, if any).

hideError Copy Section

The ui:hideError uiSchema directive will, if set to true, hide the default error display for the given field AND all of its child fields in the hierarchy.

If you need to enable the default error display of a child in the hierarchy after setting hideError: true on the parent field, simply set hideError: false on the child.

This is useful when you have a custom field or widget that utilizes either the rawErrors or the errorSchema to manipulate and/or show the error(s) for the field/widget itself.

inputType Copy Section

To change the input type (for example, tel or email) you can specify the inputType in the ui:options uiSchema directive.

import { RJSFSchema, UiSchema } from '@rjsf/utils';

const schema: RJSFSchema = { type: 'string' };
const uiSchema: UiSchema = {
  'ui:options': {
    inputType: 'tel',
  },
};

label Copy Section

Field labels are rendered by default.
Labels may be omitted on a per-field by setting the label option to false in the ui:options uiSchema directive.

import { Form } from '@rjsf/core';
import { RJSFSchema, UiSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = { type: 'string' };
const uiSchema: UiSchema = {
  'ui:options': {
    label: false,
  },
};

render(<Form schema={schema} uiSchema={uiSchema} validator={validator} />, document.getElementById('app'));

They can also be omitted globally by setting the label option to false in the ui:globalOptions uiSchema directive.

import { Form } from '@rjsf/core';
import { RJSFSchema, UiSchema } from '@rjsf/utils';
import validator from '@rjsf/validator-ajv8';

const schema: RJSFSchema = { type: 'string' };
const uiSchema: UiSchema = {
  'ui:globalOptions': {
    label: false,
  },
};

render(<Form schema={schema} uiSchema={uiSchema} validator={validator} />, document.getElementById('app'));

optionValueFormat Copy Section

Controls how enum-backed widgets (select, radio, checkboxes) encode option values in their DOM value attributes. Accepts 'indexed' (default) or 'realValue'.

• 'indexed': options are encoded as their array index (e.g. value="0", value="1"). This is the historical behavior and keeps non-primitive enum values (objects, arrays) addressable without stringifying them.
• 'realValue': primitive option values are stringified directly (e.g. value="admin", value="42", value="true"). This enables native HTML form submission and browser autocomplete since the submitted value matches the enum value. Non-primitive values (objects, arrays) still fall back to their index because String(obj) would produce "[object Object]".

The form data passed to onChange is always the typed enum value; this option only affects the DOM-level encoding. Can be specified in ui:globalOptions to apply to all enum-backed fields, or per-field in ui:options.