@gravel-form/antd

A flexible middlewares driven json schema form. The only limitation is your imagination.

Quick start

npm install @gravel-form/antd

import React from 'React';
import 'antd/dist/antd.css';
import { Form, presetMws } from "@gravel-form/antd";
const MyFirstForm = () => {
  const schema = {
    type: 'object',
    properties: {
      username: { type: 'string' },
      password: { type: 'string' },
    },
  };
  const extraProps = {
    properties: {
      password: { component: 'Password' },
    },
  };
  const [data, setData] = React.useState();
  return (
    <Form
      layout="vertical"
      middlewares={presetMws}
      schema={schema}
      extraProps={extraProps}
      data={data}
      onChange={setData}
      onSubmit={(data) => {
        alert(JSON.stringify(data, null, 2));
      }}
    />
  );
};

Playground

More examples can be found on the playground.

Props

Form

Name	Description	Type	Default
schema	A v7 json schema	JSONSchema7	-
middlewares	A list of middlewares	React.ComponentType[]	presetMws
data	Form data, if not provided initially, the data will be managed as internal state	any	-
defaultData	Default form data if it’s uncontrolled, will be ignored if data props is provieded	any	-
onChange	Trigger when form data updated	(data:any) => void	-
onSubmit	Trigger when submit button clicked, consumed by `SubmitButtonMw` or `SubmitButtonWithValidationMw`	(data:any) => void	-
extraProps	Processed by `ExtraPropsMw` in order to provide additional props to templates or form controls. Should match the structure of the schema, or customize it by replacing the middleware with your own	any	-

Following from props are directly forwarded to the antd from component.
| Name | Description | Type | Default |
|—————————|———————————————————————————————————————————————————————————————————————————————|—————————————————————|——————|
| colon | Configure the default value of colon for Form.Item. Indicates whether the colon after the label is displayed (only effective when prop layout is horizontal) | boolean | true |
| hideRequiredMark | Hide required mark for all form items | boolean | false |
| labelAlign | text align of label of all items | left | right |
| labelCol | label layout, like component. Set span offset value like {span: 3, offset: 12} or sm: {span: 3, offset: 12} | object | - |
| layout | Form layout | horizontal | vertical | inline | horizontal |
| name | Form name. Will be the prefix of Field id | string | - |
| size | Set field component size (antd components only) | small | middle | large | - |

Middleware

If you want to define you own middlewares, following props are you can consume or provide the if you are using the built-in middlewares.

Name	Description	Type
schema	Json schema	JSONSchema7Definition
parent	The middleware props of the parent node	AntdFormMiddlewareProps
data	The form data at the current node	any
onChange	Callback when form data updated	(string	number)[]
schemaPath	A array of string or number indecating the current location in the root schema	(string	number)[]
schemaPath	A array of string or number indecating the current location in the root form data	(string	number)[]
MiddlewareComponent	A composed react component of the `formProps.middlewares`, you may want to invoke it when designing a custom object/array middleware.	React.ComponentType
formProps	The root form props.	AntdFormProps
errors	A list of json schema validation erros. Provided by `LiveValidationMw` or `SubmitButtonWithValidationMw`, consumed by `FormItemTemplateMw`	Ajv.ErrorObject[]
extraProps	See following section for details	any

where JSONSchema7Definition is JSONSchema7 | boolean see here for the reason.

Practically speaking, you can add any props you in you custom middlewares base on your need.

extraProps

Click to Show the example.

jsx import { ColMw, Form, FormItemTemplateMw, RadioGroupMw, RowMw, SelectMw, schemaMws, withName, } = '@gravel-form/antd' const schema = { type: 'object', properties: { radio: { type: 'string', enum: ['op1', 'op2'] }, select: { type: 'string', enum: ['op1', 'op2'] } } } const extraProps = { properties: { radio: { component: 'RadioGroup', labels: ['Option 1', 'Option 2'], col: { span: 12 }, }, select: { col: { span: 12 }, } } } <Form middlewares={[ ExtraPropsMw, CowMw, ...schemaMws, RowMw, FormItemTemplateMw, ...withName([['RadioGroup', RadioGroupMw]]), SelectMw, ]} schema={schema} extraProps={extraProps} ></Form>

The order of the middlewares

Because the previous middlewares can intercept the following, so ordering them correctly is also important.

Usually, you may want to place the middlewares which handle more specific situaltions in the front. For example, InputMw can handle any string type whether enum props is given while SelectMw can only handle the situation when enum props is given. In this case, you may want to place SelectMw in the front so that when enum is present, SelectMw will be rendered otherwise it will fallback to InputMw. If placing InputMw in the front, then it is always intercepting.

Also, the order may depend on the hierarchy of the elements. For example, if you want the fieldset to be wrapped by Col and to wrap all the fieldset content into Row, then you may order it as ColMw, FormFieldTemplateMw, RowMw.

In the preset middleware list presetMws, the middlewares are ordered as

Root middlewares. Middlewares only apply on the root node, such as validation, submit button.
Node preprocess middlewares. ExtraPropsMw, LocalRefMw
Template middlewares. ColMw, FieldsetTemplateMw, RowMw, FormItemTemplateMw,
Schema middlewares. middlewares that process the object and array type.
Form contontrols. InputMw, DateTimeMw, SelectMw etc.
Default fallback. A middleware without any conditions, for display a error message if none of the form control middlewares can handle the current node.