@jbuschke/formik-antd
v1.5.5
Published
Dead simple declarative bindings for Formik and Ant Design.
Downloads
3,664
Maintainers
Readme
:warning: new npm package name: formik-antd
from version 1.6 and onwards this library is published under
formik-antd
, all previous versions are available under@jbuschke/formik-antd
formik-antd
Simple declarative bindings for Ant Design and Formik.
Example
import React from "react";
import { Form, Input, InputNumber, Checkbox } from "@jbuschke/formik-antd";
import { Formik } from "formik";
<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>
)}
/>
Getting started
npx create-react-app my-app
cd my-app
npm install formik antd @jbuschke/formik-antd
npm run start
Add import "antd/dist/antd.css
to your index.js
file (or look at https://ant.design/docs/react/getting-started for other options).
Core Concept
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 a supported Ant Design component from
formik-antd
(i.e.import { Input } from "@jbuschke/formik-antd"
. - Declare an instance of the component inside a
<Formik>
component. - Provide the
name
property (i.e."firstName"
).
Your components input/value state is now 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.
Core Components
To learn about Antd components just visit the official docs. Most supported components are found in the Data Entry section.
| | Name | Props | | --------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------- | | :white_check_mark: | AutoComplete | { name, validate? } & AutoCompleteProps | | :white_check_mark: | Cascader | { name, validate? } & CascaderProps | | :white_check_mark: | Checkbox | { name, validate? } & CheckboxProps | | :white_check_mark: | Checkbox.Group | { name, validate? } & CheckboxGroupProps | | :white_check_mark: | DatePicker | { name, validate? } & DatePickerProps | | :white_check_mark: | DatePicker.WeekPicker | { name, validate? } & WeekPickerProps | | :white_check_mark: | DatePicker.RangePicker | { name, validate? } & RangePickerProps | | :white_check_mark: | DatePicker.MonthPicker | { name, validate? } & MonthPickerProps | | :white_check_mark: | Input | { name, validate? } & InputProps | | :white_check_mark: | InputNumber | { name, validate? } & InputNumberProps | | :white_check_mark: | Input.Password | { name, validate? } & InputPasswordProps | | :white_check_mark: | Input.TextArea | { name, validate? } & Input.TextAreaProps | | :white_check_mark: | Mention | { name, validate? } & MentionProps | | :white_check_mark: | Radio.Group | { name, validate? } & RadioGroupProps | | :white_check_mark: | Rate | { name, validate? } & RateProps | | :white_check_mark: | Select | { name, validate? } & SelectProps | | :white_check_mark: | Slider | { name, validate? } & SliderProps | | :white_check_mark: | Switch | { name, validate? } & SwitchProps | | :white_check_mark: | TimePicker | { name, validate? } & TimePickerProps | | :white_check_mark: | Transfer | { name, validate? } & TransferProps | | :white_check_mark: | TreeSelect | { name, validate? } & TreeSelectProps |
Form- and Field-level Validation
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>
Rendering Validation Feedback
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>
Submitting and Resetting Forms
Directly under each <Formik>
container a <Form>
component should be placed (unless you do not need it). This component composes the functionality provided by Ant Designs <Form>
https://ant.design/components/form/ as well as Formiks (https://jaredpalmer.com/formik/docs/api/form):
import React from "react";
import { Form, SubmitButton, /* ... */ } from "@jbuschke/formik-antd";
import { Formik } from "formik";
<Formik>
<Form>
{/* ... */}
<SubmitButton />
</Form>
</Formik>
Submitting & Resetting
| Name | Props | Description | | ------------ | ----------------------------------------------- | ---------------------------------------------------- | | SubmitButton | Button | triggers form submission, is enabled when form valid | | ResetButton | Button | resets the form, is enabled when form dirty |
The SubmitButton must be placed inside a Form
component.
Lists and Nested objects
Nested objects and arrays can be accessed with lodash-like bracket syntax as described in the Formik documentation.
<InputField name="friends[0].firstName" />
ES imports
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: '@jbuschke/formik-antd',
libraryDirectory: 'es'
style: "css",
},
)
);
);
package.json
"scripts": {
"start": "react-app-rewired start",
"build": "react-app-rewired build"
}
Treeshaking
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).
Playground & Contributions
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).
TypeScript
Types are included.
Typechecking limitations
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.
License
MIT
Contributors
Special thanks to all contributors:
This project follows the all-contributors specification. Contributions of any kind welcome!