Form widget

Dynamically generates an HTML form out of a JSON schema using the the react-jsonschema-form library. It supports customizing the form's look and feel using a UI schema.

In-ports

json-schema Object — the JSON schema to define fields in the form and their basic properties.

ui-schema Object — the UI schema to customize the form's look and feel.

data Object — the data to enter into the form.

trigger <any> — any data event on this port triggers the state port to emit an object with current widget’s state.

settings Object — the configuration object to update widget’s settings dynamically at runtime.

Out-ports

on-submit Boolean — emits form data when the Submit button is clicked.

state Object — emits an object with details of the latest action and current form state when the form contents is updated.

Overview

This widget automatically generates HTML forms from JSON schema using the react-jsonschema-form library. It makes it easy to create both simple and complex forms with nested structures. The widget supports a variety of form fields, including text inputs, checkboxes, radio buttons, and select menus. It also provides features such as validation, conditional fields, and support for custom form elements.

To use the widget, you first need to define your form fields and their properties using a JSON schema. This schema is a JSON object that describes the structure and data types of the form fields, as well as any constraints or validation rules that should be applied to the user's input. You can also define the UI schema to customize the look and feel of your form. The UI schema is a JSON object that defines the layout and behavior of the form fields, such as their labels, placeholder text, and styles. The UI schema is optional.

To generate a form you need to pass your JSON schema and UI schema objects to the corresponding ports on the component.

To fill the form with data, you can pass an object to the data port on the component. This object should contain key-value pairs that correspond to the fields in your form, and the values will be used to pre-populate the form fields with the corresponding data.

The form can be submitted using the Submit button, or by pressing Enter if the button is disabled. Upon submission, the contents of the form will be emitted on the on-submit port, allowing you to process the form data as needed in your application. To reset the form you can pass an empty object {} to the data port on the component.

Additionally, the state port on the component will emit an event each time the contents of the form change or when an event is received on the trigger port. This can be used to track the current state of the form and respond to changes in real-time.

To help you get started with the Form widget, we will include some simple examples that demonstrate how to use JSON schema and UI schema to define and customize forms. For more advanced examples and live demos, you can visit the react-jsonschema-form playground.

Simple log-in form

Generate this simple log-in form using the Form widget. Use the JSON schema and UI schema given below.

JSON schema:

{
  "title": "Log-in form",
  "description": "A simple log-in form with two fields and a checkbox.",
  "type": "object",
  "properties": {
    "username": {
      "title": "Username",
      "type": "string"
    },
    "password": {
      "title": "Password",
      "type": "string"
    },
    "checkbox": {
      "title": "Remember me",
      "type": "boolean",
      "enum": [
        true,
        false
      ]
    }
  }
}

UI schema:

{
  "username": {
    "ui:autofocus": true,
    "ui:emptyValue": ""
  },
  "password": {
    "ui:widget": "password",
    "ui:help": "Hint: Make it strong!"
  }
}

This schema will generate a form with two fields: a text input for the username and a password input for the password. The ui:autofocus attribute on the username field will cause the cursor to be automatically focused on that field when the form is rendered, and the ui:emptyValue attribute will specify an empty value for the field. The ui:widget attribute on the password field will specify that the field should use the password input widget, and the ui:help attribute will display a helpful message beneath the field.

Settings

Title

Widget’s title.

Hide progress bar

Controls the visibility of the widget’s progress bar. By default, the progress bar is visible.

Live Validation

Enables validation on form change. By default, form validation occurs only on submission.

Hide Submit button

Controls the visibility of the Submit button. By default, the button is visible.

Button text

Sets a custom text for the Submit button.

Button alignment

Sets the Submit button alignment.

• center — aligns the button to be equally spaced from the left and right side of the form.
• left — aligns the button to the left side of the form.
• right — aligns the button to the right side of the form.

Button intent

Sets the Submit button color to visually express its intent.

• none — grey button. Neutral state. (default).
• primary — blue button to highlight it on the page.
• success — green button to denote success and safe operations.
• warning — orange button to denote warnings or intermediate states.
• danger — red button to denote errors or potentially destructive operations.

Custom error messages

Specify custom error messages to be displayed by the widget. You can set a message for each error code.