Form

A conditionally stateful Form wrapper. This component maintains state and validation of any child FormField components. It utilizes Formik and can receive props related to configuring Formik.

Validation Sync and Async Form and Field level validation is available through the validate prop.

import { Alert } from '@emoney/kyber';

<Alert>
    Check out the <a href="#/Tutorials/Intro%20To%20Forms">Intro To Forms Tutorial</a> to get
    familiar with how forms work in React with Kyber.
</Alert>;

Basic Example

Wrap the Kyber form field component you would like to use in a FormField and place it inside the Form component. You will need to provide an id and label prop to the FormField. Set the name prop on the field component, this will be used as the key in the returned data.

Result

Loading...

Live Editor

<Form onSubmit={(values, actions) => { actions.setSubmitting(false); console.log(values); }} > <FormField> <TextField label="Label" name="textfield" /> </FormField> </Form>

<Form
    onSubmit={(values, actions) => {
        actions.setSubmitting(false);
        console.log(values);
    }}
>
    <FormField>
        <TextField label="Label" name="textfield" />
    </FormField>
</Form>

Validation

The Form and related FormField components support multiple types of validation.

The preferred order of validation is:

1. Form level schema validation with yup.
2. Form level synchronous validation.
3. Form level asynchronous validation.
4. Field level synchronous validation (See FormField).
5. Field level synchronous validation (See FormField).

Validation Library

Yup is a powerful validation library that can be used with the Form component. There are a lot of options and ways that Yup validation schemas can be constructed. Review the Yup Documentation for full details.

Form Level Schema Validation

Result

Loading...

Live Editor

const schema = object().shape({ textfield: string().required(), }); render( <Form onSubmit={(values, actions) => { actions.setSubmitting(false); console.log(values); }} validationSchema={schema} > <FormField> <TextField label="Label" name="textfield" /> </FormField> </Form>, );

const schema = object().shape({
    textfield: string().required(),
});

render(
    <Form
        onSubmit={(values, actions) => {
            actions.setSubmitting(false);
            console.log(values);
        }}
        validationSchema={schema}
    >
        <FormField>
            <TextField label="Label" name="textfield" />
        </FormField>
    </Form>,
);

Sync Form Level Validation

Result

Loading...

Live Editor

<Form id="sync-form-level" onSubmit={(values, actions) => { actions.setSubmitting(false); console.log(values); }} validate={(values, actions) => { if (values.textfield === 'a') { return { textfield: 'Cannot be a', }; } }} > <FormField id="sync-form-level-textfield" label="Label" description="Try setting to 'a'"> <TextField name="textfield" /> </FormField> </Form>

<Form
    id="sync-form-level"
    onSubmit={(values, actions) => {
        actions.setSubmitting(false);
        console.log(values);
    }}
    validate={(values, actions) => {
        if (values.textfield === 'a') {
            return {
                textfield: 'Cannot be a',
            };
        }
    }}
>
    <FormField id="sync-form-level-textfield" label="Label" description="Try setting to 'a'">
        <TextField name="textfield" />
    </FormField>
</Form>

Async Form Level Validation

Result

Loading...

Live Editor

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); render( <Form onSubmit={(values, actions) => { actions.setSubmitting(false); console.log(values); }} validate={(values, actions) => sleep(2000).then(() => { if (values.textfield === 'a') { return { textfield: 'Cannot be a', }; } }) } > <FormField> <TextField name="textfield" label="Label" description="Try setting to 'a'" /> </FormField> </Form>, );

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

render(
    <Form
        onSubmit={(values, actions) => {
            actions.setSubmitting(false);
            console.log(values);
        }}
        validate={(values, actions) =>
            sleep(2000).then(() => {
                if (values.textfield === 'a') {
                    return {
                        textfield: 'Cannot be a',
                    };
                }
            })
        }
    >
        <FormField>
            <TextField name="textfield" label="Label" description="Try setting to 'a'" />
        </FormField>
    </Form>,
);

Other Validation Uses

Toggling Field Validation

Sometimes it may be necessary to alter form behavior based on local or external state. A common case is that validation changes based on state changes.

You can do this by using Yup's when method to conditionaly add validation based on the value of another field.

Result

Loading...

Live Editor

function Example() { const [isEnabled, setIsEnabled] = React.useState(true); const initialValue = { switch: isEnabled && 'on', }; const schema = object().shape({ disabled: string().when('switch', { is: 'on', then: string().required() }), conditional: string().when('switch', { is: 'on', then: string().required() }), }); return ( <Form initialValues={initialValue} validationSchema={schema} onSubmit={(values, actions) => { console.log(values); actions.setSubmitting(false); }} > <FormField> <Switch label={`Field ${isEnabled ? 'Enabled' : 'Disabled'}`} name="switch" onChange={(payload) => setIsEnabled(payload.checked)} /> </FormField> <FormField> <TextField label="Disabled Field" name="disabled" disabled={!isEnabled} /> </FormField> {isEnabled && ( <FormField> <TextField label="Conditionally Rendered Field" name="conditional" /> </FormField> )} </Form> ); }

function Example() {
    const [isEnabled, setIsEnabled] = React.useState(true);

    const initialValue = {
        switch: isEnabled && 'on',
    };

    const schema = object().shape({
        disabled: string().when('switch', { is: 'on', then: string().required() }),
        conditional: string().when('switch', { is: 'on', then: string().required() }),
    });

    return (
        <Form
            initialValues={initialValue}
            validationSchema={schema}
            onSubmit={(values, actions) => {
                console.log(values);
                actions.setSubmitting(false);
            }}
        >
            <FormField>
                <Switch
                    label={`Field ${isEnabled ? 'Enabled' : 'Disabled'}`}
                    name="switch"
                    onChange={(payload) => setIsEnabled(payload.checked)}
                />
            </FormField>

            <FormField>
                <TextField label="Disabled Field" name="disabled" disabled={!isEnabled} />
            </FormField>

            {isEnabled && (
                <FormField>
                    <TextField label="Conditionally Rendered Field" name="conditional" />
                </FormField>
            )}
        </Form>
    );
}

Cross Field Validation

Result

Loading...

Live Editor

function Example() { const schema = object().shape({ age: number().required(), retirement_age: number().required().min(ref('age'), '${path} can not be less than Age'), }); return ( <Form validationSchema={schema} onSubmit={(values, actions) => { console.log(values); actions.setSubmitting(false); }} > <FormField> <NumberField label="Age" name="age" /> </FormField> <FormField> <NumberField label="Retirement Age" description="Set less than Age" name="retirement_age" /> </FormField> </Form> ); }

function Example() {
    const schema = object().shape({
        age: number().required(),
        retirement_age: number().required().min(ref('age'), '${path} can not be less than Age'),
    });

    return (
        <Form
            validationSchema={schema}
            onSubmit={(values, actions) => {
                console.log(values);
                actions.setSubmitting(false);
            }}
        >
            <FormField>
                <NumberField label="Age" name="age" />
            </FormField>

            <FormField>
                <NumberField
                    label="Retirement Age"
                    description="Set less than Age"
                    name="retirement_age"
                />
            </FormField>
        </Form>
    );
}

Custom footer

You can also replace the Form's footer by using the footerRenderer prop on the Form. Alternatively you can set this prop to null to disable the footer entirely.

Note: If you add type="submit" to one of your buttons it will be used as the submit button.

Result

Loading...

Live Editor

// The function receives the Form components props as the first parameter in case you need them const renderCustomFooter = (props) => { return ( <Button id="demo-button" type="submit"> My Custom Button </Button> ); }; function Example() { const handleSubmit = (values, actions) => { actions.setSubmitting(false); console.log(values); }; return ( <Form onSubmit={handleSubmit} footerRenderer={renderCustomFooter}> <FormField> <TextField label="Label" name="textfield" /> </FormField> </Form> ); } render(<Example />);

// The function receives the Form components props as the first parameter in case you need them
const renderCustomFooter = (props) => {
    return (
        <Button id="demo-button" type="submit">
            My Custom Button
        </Button>
    );
};

function Example() {
    const handleSubmit = (values, actions) => {
        actions.setSubmitting(false);
        console.log(values);
    };

    return (
        <Form onSubmit={handleSubmit} footerRenderer={renderCustomFooter}>
            <FormField>
                <TextField label="Label" name="textfield" />
            </FormField>
        </Form>
    );
}

render(<Example />);

Further Customization

With children As A Render Prop

See Formik for more details about the props that are forwarded to children.

Result

Loading...

Live Editor

<Form onSubmit={(values, actions) => { actions.setSubmitting(false); console.log({ values }); }} > {({ submitCount, dirty }) => ( <> <p>Is dirty? {dirty.toString()}</p> <p>Number of times submitted: {submitCount}</p> <FormField> <TextField label="Label" name="textfield" /> </FormField> </> )} </Form>

<Form
    onSubmit={(values, actions) => {
        actions.setSubmitting(false);
        console.log({ values });
    }}
>
    {({ submitCount, dirty }) => (
        <>
            <p>Is dirty? {dirty.toString()}</p>

            <p>Number of times submitted: {submitCount}</p>

            <FormField>
                <TextField label="Label" name="textfield" />
            </FormField>
        </>
    )}
</Form>

Using Formik Context

It's possible to directly use the Formik context within a subcomponent of a Form. Either as the Formik published hook or through direct access with of the FormikContext object and useContext hook.

Result

Loading...

Live Editor

function SubComponent() { const { dirty, submitCount } = useFormikContext(); return ( <> <p>Is dirty? {dirty.toString()}</p> <p>Number of times submitted: {submitCount}</p> </> ); } render( <Form onSubmit={(values, actions) => { actions.setSubmitting(false); console.log({ values }); }} > <SubComponent /> <FormField> <TextField label="Label" name="textfield" /> </FormField> </Form>, );

function SubComponent() {
    const { dirty, submitCount } = useFormikContext();

    return (
        <>
            <p>Is dirty? {dirty.toString()}</p>

            <p>Number of times submitted: {submitCount}</p>
        </>
    );
}

render(
    <Form
        onSubmit={(values, actions) => {
            actions.setSubmitting(false);
            console.log({ values });
        }}
    >
        <SubComponent />

        <FormField>
            <TextField label="Label" name="textfield" />
        </FormField>
    </Form>,
);

Using the Form Ref

The Form's ref prop will return a reference to the Formik instance. This gives you access to Formik's props and methods which let you control the form's state manually. For example this can be used to reset the form and clear out the field values.

Resetting the Form

Result

Loading...

Live Editor

function Example() { const formRef = useRef(); const handleSubmit = (values, actions) => { actions.setSubmitting(false); console.log(values); }; const handleSecondaryButtonClick = (event) => { console.log(formRef.current); console.log('secondary button clicked'); formRef.current.resetForm(); }; return ( <Form onSubmit={handleSubmit} onSecondaryButtonClick={handleSecondaryButtonClick} secondaryButtonContents="Reset form" submitButtonContents="Submit button text" ref={formRef} > <FormField> <TextField label="Label" name="textfield" /> </FormField> </Form> ); }

function Example() {
    const formRef = useRef();

    const handleSubmit = (values, actions) => {
        actions.setSubmitting(false);
        console.log(values);
    };

    const handleSecondaryButtonClick = (event) => {
        console.log(formRef.current);
        console.log('secondary button clicked');
        formRef.current.resetForm();
    };

    return (
        <Form
            onSubmit={handleSubmit}
            onSecondaryButtonClick={handleSecondaryButtonClick}
            secondaryButtonContents="Reset form"
            submitButtonContents="Submit button text"
            ref={formRef}
        >
            <FormField>
                <TextField label="Label" name="textfield" />
            </FormField>
        </Form>
    );
}

Nested Values

Result

Loading...

Live Editor

const options = [ { name: 'Georgia', value: 'GA', }, { name: 'Iowa', value: 'IA', }, ]; render( <Form onSubmit={(values, actions) => { actions.setSubmitting(false); console.log(values); }} initialValues={{ test: { checkbox: false, group: ['a', 'b', 'd'], select: 'GA', multiple: ['GA', 'IA'] }, }} initialErrors={{ test: { stuff: 'Has an initial error' } }} initialTouched={{ test: { stuff: true } }} > <FormField> <TextField label="Label" name="test.stuff" /> </FormField> <FormField> <Checkbox label="Checkbox" name="test.checkbox" /> </FormField> <FormField> <CheckboxGroup label="Group" name="test.group"> <CheckboxGroup.Item value="a" label="A" /> <CheckboxGroup.Item value="b" label="B" /> <CheckboxGroup.Item value="c" label="C" /> <CheckboxGroup.Item value="d" label="D" /> </CheckboxGroup> </FormField> <FormField> <Select label="Select" name="test.select"> {options.map((option) => ( <Item id={`nested-select-${option.value}`} key={option.value} {...option}> {option.name} </Item> ))} </Select> </FormField> <FormField> <MultiSelect label="MultiSelect" name="test.multiple"> {options.map((option) => ( <Item id={`nested-multiple-${option.value}`} key={option.value} {...option}> {option.name} </Item> ))} </MultiSelect> </FormField> </Form>, );

const options = [
    {
        name: 'Georgia',
        value: 'GA',
    },
    {
        name: 'Iowa',
        value: 'IA',
    },
];

render(
    <Form
        onSubmit={(values, actions) => {
            actions.setSubmitting(false);
            console.log(values);
        }}
        initialValues={{
            test: { checkbox: false, group: ['a', 'b', 'd'], select: 'GA', multiple: ['GA', 'IA'] },
        }}
        initialErrors={{ test: { stuff: 'Has an initial error' } }}
        initialTouched={{ test: { stuff: true } }}
    >
        <FormField>
            <TextField label="Label" name="test.stuff" />
        </FormField>

        <FormField>
            <Checkbox label="Checkbox" name="test.checkbox" />
        </FormField>

        <FormField>
            <CheckboxGroup label="Group" name="test.group">
                <CheckboxGroup.Item value="a" label="A" />
                <CheckboxGroup.Item value="b" label="B" />
                <CheckboxGroup.Item value="c" label="C" />
                <CheckboxGroup.Item value="d" label="D" />
            </CheckboxGroup>
        </FormField>

        <FormField>
            <Select label="Select" name="test.select">
                {options.map((option) => (
                    <Item id={`nested-select-${option.value}`} key={option.value} {...option}>
                        {option.name}
                    </Item>
                ))}
            </Select>
        </FormField>

        <FormField>
            <MultiSelect label="MultiSelect" name="test.multiple">
                {options.map((option) => (
                    <Item id={`nested-multiple-${option.value}`} key={option.value} {...option}>
                        {option.name}
                    </Item>
                ))}
            </MultiSelect>
        </FormField>
    </Form>,
);

Analytics

The Form component is trackable through Kyber Analytics. This is the default analytics config.

export default {
	value: 'Form',
	actions: {
		onSubmit: { type: 'FORM_SUBMIT', payload: 'Submit' },
	},
};

Props