Newton's Preposterous Miscalculation

    heur-design
    TypeScript icon, indicating that this package has built-in type declarations

    0.4.0 • Public • Published

    Build Status All Contributors license

    CodeSandbox

    ⚠️ 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 "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 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:

    1. Import a supported Ant Design component from formik-antd (i.e. import { Input } from "formik-antd".
    2. Declare an instance of the component inside a <Formik> component.
    3. Provide the name property.

    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
    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
    TimePicker { name, validate? } & TimePickerProps
    Transfer { name, validate? } & TransferProps
    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 "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.

    <Input name="friends[0].firstName" />

    ES imports

    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

    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:

    Nile Daley
    Nile Daley

    💻
    James W Mann
    James W Mann

    💻
    Jannik Buschke
    Jannik Buschke

    💻
    Lars-Jørgen Kristiansen
    Lars-Jørgen Kristiansen

    💻
    Adam
    Adam

    💻
    jeessy2
    jeessy2

    💻
    Pavan Agrawal
    Pavan Agrawal

    📖
    Khartir
    Khartir

    💻
    Yury Kozhenov
    Yury Kozhenov

    💻
    Tonye Jack
    Tonye Jack

    💻
    Edon Gashi
    Edon Gashi

    🚇

    This project follows the all-contributors specification. Contributions of any kind welcome!

    Install

    npm i heur-design

    DownloadsWeekly Downloads

    12

    Version

    0.4.0

    License

    MIT

    Unpacked Size

    166 kB

    Total Files

    342

    Last publish

    Collaborators

    • avatar