Skip to main content

JSON Form

The JSON form widget saves time and effort by automatically generating forms from JSON data, eliminating the need for manual form creation.

Configure JSON Form Widget

Generate JSON Form

To populate the JSON Form widget with data, you can utilize the Source Data property, which requires the data to be structured in a JSON format:

{
"name": "John",
"date_of_birth": "20/02/1990",
"age": 29,
"employee_id": 1001
}

JSON Form automatically detects the appropriate field type for each value. For instance, if the JSON data contains an age field, it sets the field type to a Number Input. Additionally, you can add/customize field types using the Field Configuration property.

You can display dynamic data in a JSON Form widget by binding the response from a query or a JS function to the Source Data property. This allows the form to update dynamically as the data changes in the database or API.


Example: suppose you want a master-detail form that shows details of each record in a form when you select a row in a table. Suppose you have fetched data from the mock database using a SELECT query fetchUserData. You can display the fetched data by binding the query response to the Table Data property of the Table widget tblUserData, as shown below:

{{fetchUserData.data}}

To automatically generate the fields in the JSON Form when a table row is selected, add the below code in the Source Data property:

{{tbluserData.selectedRow}}

You can click on an individual row in the Table and update data in the form fields.

Auto generate form

You can enable the Auto Generate Form property to have the form fields regenerate automatically when the source data changes, for example, when keys in the JSON data change or if a data type changes, for example, from string to a number.

However, it's important to note that enabling this feature overrides any custom configurations that you are providing through data transformations using JavaScript.

Field configuration

In the Field Configuration section of the JSON Form's property pane, you can add fields or update each field's settings by clicking the cog icon ⚙︎ next to it. You can customize each form field using properties, for instance, updating the field type, setting validation and style properties, and triggering actions using event listeners. You can select any one of the following options from the Field Type property to update the widget type for that field on the JSON Form:

  • Array
  • Checkbox
  • Currency Input
  • Datepicker
  • Email Input
  • Multiselect
  • Multi-line Text Input
  • Number Input
  • Object
  • Password Input
  • Phone Number Input
  • Radio Group
  • Select
  • Switch
  • Text Input

Each field type has different sets of events and configurations that can be customized. For example, the Number Input field can have a min and max value, while the Datepicker field can have a specific date format.

The configuration options for each field type may include default values, placeholder text, validation rules, and more. These options can be adjusted to fit the specific needs of the form being created.

Submit form data

To access form data, the values entered in the JSON form are stored in the formData property. For instance, if you have a JSON form with a name field, you can access its value using:

{{JSONForm.formData.name}}

To submit form data, you can use the onSubmit event. This event allows you to perform an action when the user submits the form.

Suppose you have a database with user information name, gender, and email and you want to insert data collected through the JSON Form. To do this, you can create an SQL insert query and pass the data as shown:

INSERT INTO users
(name, gender, email)
VALUES
(
{{JSONForm1.formData.name}},
{{JSONForm1.formData.gender}},
{{JSONForm1.formData.email}}
);

To trigger this insert query, you can set the onSubmit event of the Submit button on the JSON Form.

Form validation

Validating user input is essential for ensuring correct and formatted data. Appsmith provides validation properties such as Valid, Regex, and Required for Fields property.

  • The Valid property, which checks input against a code expression,
  • The Regex property, which checks that input matches a regular expression,
  • The Required property, which indicates that the field must be filled out.

When Disabled Invalid Forms is turned on, the JSON Form widget checks the validation properties, and the Submit button is automatically disabled if there are failing checks. Using this property guarantees that all user input meets the criteria you have defined in the form fields.

Clear form fields

To clear form fields, you can enable the Show Reset property. When the Show Reset property is enabled, a reset button is added to the form. Clicking this button resets all fields in the form to their default values. This is useful if a user wants to start over with a new entry or if they entered the wrong information and need to clear the form.

Properties

Properties allow you to edit the widget, connect it with other widgets and customize the user actions.

Widget properties

These properties are present in the property pane of the widget. The following table lists all the widget properties.

PropertyData typeDescription
TitleStringSets the text that appears at the top of the form as a title.
Source DataJSONTakes a JSON object whose data is used to generate the form layout.
Auto Generate formBooleanWhen enabled, the form layout updates automatically when the field types inside the Source Data are changed.
Generate FormButtonWhen Auto Generate Form is disabled, this button manually regenerates the form layout according to the field types in the Source Data object.
Field ConfigurationListThis is a list of the generated form fields. Click the gear icon to further customize any of these fields, or the eye icon to hide that field. They can also be re-ordered by dragging, and renamed by clicking their names.
Add New FieldButtonAdds a new field in the form. Fields added this way are known as custom fields. You can delete these fields later.
Disable Invalid FormsBooleanDisables the submit button when one or more of the form fields are considered invalid.
Animate LoadingBooleanWhen turned off, the widget loads without any skeletal animation. You can use a toggle switch to turn it on/off. You can also turn it off/on using javascript by enabling the JS label next to it.
Fixed FooterBooleanMakes the footer sticky for long forms, so the Submit and Reset buttons are always visible on long forms.
VisibleBooleanControls widget's visibility on the page. When turned off: The widget would not be visible when the app is published. It appears translucent when in Edit mode.
Hidden Fields in DataBooleanWhen turned on, the output data is updated to contain data from hidden fields. The hidden field values are referenced from the source data.
Scroll ContentsBooleanMakes the contents of the form scrollable.
Show ResetBooleanWhen enabled, shows a reset button in the form allowing users to reset the form at any time.
Submit Button LabelStringSets the text for the label on the Submit button.
Reset Button LabelStringSets the text for the label on the Reset button.
HeightStringIt configures how a widget’s height reacts to content changes. It has three possible configurations:
Fixed: The height of the widget remains as set using drag and resize.
Auto Height: The height of the widget reacts to content changes. In JSON form widget, auto height is enabled by default.
Auto Height with limits: Same as Auto height, with a configurable option to set the minimum and maximum number of rows that can be occupied by the widget.

Reference properties

These properties can be referenced in other widgets, queries, or JS functions using the dot operator. For instance, to get the formData, you can use JSONFrom1.formData.

PropertyData TypeDescription
fieldStateObject8A JSON object describing the state of each field in the form. State data includes: isDisabled, isRequired, isVisible, and isValid
e.g. { "name": {"isVisible": true, ... }, ... }
formDataObjectContains a JSON object with the field names and their current values in the form.
isValidBooleanReflects whether the widget's inputs are considered Valid.
sourceDataObjectContains a JSON object of the original source data which was bound to the form.

Styles properties

Style properties allow you to change the look and feel of the widget.

PropertyData typeDescription
Background ColorStringSets the background color of the widget. Accepts CSS color values.
Border RadiusStringRounds the corners of the widget's outer edge. With JS enabled, this accepts valid CSS border-radius values.
Border WidthNumberSets the width of the widget's border. Accepts number values only, in px.
Box ShadowStringCasts a drop shadow from the frame of the widget. With JS enabled, this accepts valid CSS box-shadow values.
Border ColorStringSets the Border color of the widget.
Button ColorStringSets the color of the submit and reset button. Accepts valid CSS color values.
Button VariantStringSets the button style type to represent its significance - Primary, Secondary, or Tertiary. You can use JavaScript to set this field by writing code that evaluates to the "PRIMARY", "SECONDARY", or "TERTIARY".
Border RadiusStringRounds the corners of the widget's outer edge. With JS enabled, this accepts valid CSS border-radius values.
Box ShadowStringCasts a drop shadow from the frame of the widget. With JS enabled, this accepts valid CSS box-shadow values.
IconStringSets an icon to be included on the submit and reset button.
PlacementStringDefines where the button's icon and label appear within the space of the button. Start: The icon and label appear at the left-most side of the button; Center: The icon and label appear in the center of the button space; Between: The icon and label appear at opposite ends of the button's space. You can use JavaScript to set this field by writing code that evaluates to the "START", "CENTER", or "BETWEEN".
PositionStringSets whether the icon appears on the left or right of the button's label text.

Events

These are functions that are called when event listeners are triggered in the widget. Use actions to execute tasks based on user events.

Event nameDescription
onSubmitSets an action to take place when the user clicks the Submit button on this form.

Troubleshooting

Here are some common errors that you may see when using the JSON Form widget:

If you encounter other issues while working with the widget, see widget errors. If the guide doesn't cover your issue, contact the support team.