@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<AntdFormMiddlewareProps>[]	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 <Col> 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<AntdFormMiddlewareProps>
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

The shap of the extraProps depends on the middlewares consuming it. If you are using ExtraPropsMw then the formProps.extraProps should match the structure of the schema so that ExtraPropsMw is able to retreat the related node base on the current schema path. Following is a list of props that you can set if you are using the built-in middlewares.

properties	Consumer	Description
component	Middlewares wraped by the withName	multiple middlewares may support the same schema, so that you can use this property to pick the desired one
row	RowMw	props forwared to ant design Row component
col	ColMw	props forwared to ant design Col component
labels	SelectMw, RadioGroupMw, CheckboxGroupMw	to display a different text on the UI instead of the enum value
formItem	FormItemTemplateMw	props forwared to ant design Form.Item component
props	Any form controls	props forwared to ant design Col component

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 }, } } }

```

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.