✨ Ant Design 4 and compatability
Ant Design 4 is landing soon. A beta that works with Ant Designs release candidate is available (v2.*-beta). Version 1 of this library supports Ant Design v3. Version 2 of this library supports Ant Design 4. Both v1 and v2 of this library work with formik v1 and v2.
from version 1.6 and onwards this library is published under
formik-antd
, all previous versions are available under@jbuschke/formik-antd
. In order to upgrade: change the referenced package name in your package.json as well as all imports. I.e. replaceimport { Input } from "@jbuschke/formik-antd
withimport { Input } from "formik-antd
.
Simple declarative bindings for Ant Design and Formik.
import React from 'react'
import { Form, Input, InputNumber, Checkbox } from 'formik-antd'
import { Formik } from 'formik'
function App() {
return (
<Formik
initialValues={{ firstName: '', age: 20, newsletter: false }}
render={() => (
<Form>
<Input name='firstName' placeholder='First Name' />
<InputNumber name='age' min={0} />
<Checkbox name='newsletter'>Newsletter</Checkbox>
</Form>
)}
/>
)
}
npm install formik-antd
Add import "antd/dist/antd.css
to your index.js
file (or look at https://ant.design/docs/react/getting-started for other options).
This library enriches several Ant Design components with a name: string
property that connects them to a Formik form field. It is pretty simple:
Import one of the supported components and set the name
prop. Now the component is connected/synced with the corresponding Formik
field!
The Ant Design components are feature rich and provide a lot of props to customize their vizual presentation. These features and also their apis stay the same. Visit their documentation to learn more.
Name | Props | |
---|---|---|
✅ | AutoComplete | { name, validate? } & AutoCompleteProps |
✅ | Cascader | { name, validate? } & CascaderProps |
✅ | Checkbox | { name, validate? } & CheckboxProps |
✅ | Checkbox.Group | { name, validate? } & CheckboxGroupProps |
✅ | DatePicker | { name, validate? } & DatePickerProps |
✅ | DatePicker.WeekPicker | { name, validate? } & WeekPickerProps |
✅ | DatePicker.RangePicker | { name, validate? } & RangePickerProps |
✅ | DatePicker.MonthPicker | { name, validate? } & MonthPickerProps |
✅ | Input | { name, validate? } & InputProps |
✅ | InputNumber | { name, validate? } & InputNumberProps |
✅ | Input.Password | { name, validate? } & InputPasswordProps |
✅ | Input.TextArea | { name, validate? } & Input.TextAreaProps |
✅ | Mention | { name, validate? } & MentionProps |
✅ | Radio.Group | { name, validate? } & RadioGroupProps |
✅ | Rate | { name, validate? } & RateProps |
✅ | Select | { name, validate? } & SelectProps |
✅ | Slider | { name, validate? } & SliderProps |
✅ | Switch | { name, validate? } & SwitchProps |
✅ | Table | { name } & TableProps |
✅ | TimePicker | { name, validate? } & TimePickerProps |
✅ | Transfer | { name, validate? } & TransferProps |
✅ | TreeSelect | { name, validate? } & TreeSelectProps |
Directly under each <Formik>
container a <Form>
component should be placed. This component composes the functionality provided by Ant Designs (https://ant.design/components/form/) as well as Formiks (https://jaredpalmer.com/formik/docs/api/form) <Form>
components:
import React from 'react'
import { Form, SubmitButton, ResetButton /* ... */ } from 'formik-antd'
import { Formik } from 'formik'
function App() {
return <Formik initialValues={/* ... */} onSubmit={/* ... */}>
<Form>
{/* ... */}
<SubmitButton />
<ResetButton />
</Form>
</Formik>
}
Formik provides form- and field-level validation callbacks to provide validation logic. How to validate is neither part of formik nor of this library.
Form-level validation is done by setting formiks validate
prop. Field-level validation is optional available on the components. Additional to the name
prop formiks optional validate?: (value: any) => undefined | string | Promise<any>
is added to all core components to allow field-level validation.
There is one special case to be aware of when using field-level validation: When using the Form.Item
component with another Antd-field component, the validate
prop has to be added to the Form.Item
, not the input component:
<Form.Item name='firstName' validate={validator}>
<Input name='firstName' />
</Form.Item>
Showing validation messages can be accomplished with the Form.Item
component (or FormItem
which is the same). It
- renders error messages if the field has been touched and the corresponding field has a validation error (and changes the border color of enclosed input component to red).
- renders a green success icon messages if it's
showValidateSuccess: boolean
prop is set to true, the field has been touched and the corresponding field does not have a validation error. - exposes some layout features and a label (visit https://ant.design/components/form/ for the details).
<Form.Item name='firstName'>
<Input name='firstName' />
</Form.Item>
The table components comes with additional helper buttons to add and delete rows. An example can be seen in the codesandbox.
Two additional helper components to submit and reset forms are provided: SubmitButton
and ResetButton
. Both render an Ant Design button and can be customized accordingly (docs). The ResetButton
is disabled if the form is not dirty. To override the default behavior provide the disable: boolean
prop.
Nested objects and arrays can be accessed with lodash-like bracket syntax as described in the Formik documentation.
<Input name='friends[0].firstName' />
If you do not want to import the full ant design library and its stylesheet (in order to reduce the bundle size) you can import specific components and their stylesheet by their path, as it is described in the antd documentation https://ant.design/docs/react/getting-started#Import-on-Demand
import Input from 'formik-antd/es/input'
import 'formik-antd/es/input/style'
Some build tools like webpack are now able to "tree shake", meaning unused code from ant design will not be bundled.
As writing imports like this is a little cumbersome there is a babel import helper: https://github.com/ant-design/babel-plugin-import. In create-react-app
projects babel plugins do not work out of the box. With third party projects like customize-cra
and react-app-rewired
we are able to change the webpack config. Be warned though, the team behind create-react-app
does not support this scenario, so if you run into problems you are on your own.
npm install babel-plugin-import customize-cra react-app-rewired --save-dev
config-overrides.js
const path = require('path')
const { override, fixBabelImports } = require('customize-cra')
module.exports = override(
fixBabelImports('antd', {
libraryName: 'antd',
libraryDirectory: 'es',
style: 'css',
}),
fixBabelImports('formik-antd',
{
libraryName: 'formik-antd',
libraryDirectory: 'es'
style: "css",
},
)
);
package.json
"scripts": {
"start": "react-app-rewired start",
"build": "react-app-rewired build"
}
Treeshaking with ant design is currently kind of broken, as generally all icons are imported. This will be fixed as of ant design v4 (might be ready in 2019).
If you want to dig into the source code and test locally you can use https://github.com/jannikbuschke/Formik-antd-playground (clone with the --recursive flag and follow the README, its pretty simple).
Types are included.
Form values currently cannot be typechecked (at least to my knowledge). For example the following ideally would give a compile error:
<Formik<{name:string}> initialValues={{name:""}}>
<Input name="naem" />
</Formik>
Typescript cannot (yet) enforce types of children. In the future this hopefully will be possible.
MIT
Special thanks to all contributors:
Nile Daley 💻 |
James W Mann 💻 |
Jannik Buschke 💻 |
Lars-Jørgen Kristiansen 💻 |
Adam 💻 |
jeessy2 💻 |
Pavan Agrawal 📖 |
Khartir 💻 |
Yury Kozhenov 💻 |
Tonye Jack 💻 |
Edon Gashi 🚇 |
Roman Tsegelskyi 💻 |
Daniel Schulz 💻 |
This project follows the all-contributors specification. Contributions of any kind welcome!