Intro

The @emoney/kyber-forms package can be used to create any type of form. The examples in this readme are oriented from simple to complex.

Fields

Kyber's form components are stateless high level components that encapsulate serialization and validation. Most of them can be used uncontrolled or controlled. Each field component has the following shared props:

Prop Name	Type	Description
desc	string	The description for the field.
disabled	boolean	Whether or not the field is disabled.
errorText	string	The error text to display if isInvalid is true.
isInvalid	boolean	Whether or not the field is invalid.
isValid	boolean	Whether or not the field is valid.
isWarning	boolean	Whether or not the field is warning.
label	string	The label for the field.
name	string	The name of the field. This is used to serialize the form data.
radius	string	The radius of the field. One of round, square, or pill.
readOnly	boolean	Whether or not the field is read only.
renderEndAddOn	function	A function that returns a React node to render at the end of the field. Use one InputGroup component, Button, or Dropdown.
renderPrefix	function	A function that returns a React node.
renderStartAddOn	function	A function that returns a React node to render at the start of the field. Use one InputGroup component, Button, or Dropdown.
renderSuffix	function	A function that returns a React node.
size	string	The size of the field. One of sm, md, or lg.
validText	string	The valid text to display if isValid is true.
warningText	string	The warning text to display if isWarning is true.

Validation States

Result

Loading...

Live Editor

<div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, minmax(100px, auto))', gridGap: '1rem', }} > <TextField label="Valid" name="valid" isValid validText="This field is valid" value="Valid" /> <TextField label="Invalid" name="invalid" errorText="This field is invalid" isInvalid value="Invalid" /> <TextField label="Warning" name="warning" isWarning warningText="This field has a warning" value="Warning" /> </div>

<div
    style={{
        display: 'grid',
        gridTemplateColumns: 'repeat(3, minmax(100px, auto))',
        gridGap: '1rem',
    }}
>
    <TextField label="Valid" name="valid" isValid validText="This field is valid" value="Valid" />
    <TextField
        label="Invalid"
        name="invalid"
        errorText="This field is invalid"
        isInvalid
        value="Invalid"
    />
    <TextField
        label="Warning"
        name="warning"
        isWarning
        warningText="This field has a warning"
        value="Warning"
    />
</div>

Addons, Prefixes, and Suffixes

Result

Loading...

Live Editor

<div style={{ display: 'grid', gridGap: '1rem' }}> <TextField renderStartAddOn={() => <InputGroup.Text>Start AddOn</InputGroup.Text>} renderEndAddOn={() => <InputGroup.Text>End AddOn</InputGroup.Text>} renderPrefix={() => 'Prefix'} renderSuffix={() => 'Suffix'} /> <TextField renderStartAddOn={() => <Button variant="outline-secondary">Start AddOn</Button>} renderEndAddOn={() => <Button variant="outline-secondary">End AddOn</Button>} renderPrefix={() => 'Prefix'} renderSuffix={() => 'Suffix'} /> <TextField renderStartAddOn={() => ( <DropdownButton title="Start AddOn" variant="outline-secondary"> <DropdownItem>Item</DropdownItem> </DropdownButton> )} renderEndAddOn={() => ( <DropdownButton title="End AddOn" variant="outline-secondary"> <DropdownItem>Item</DropdownItem> </DropdownButton> )} renderPrefix={() => 'Prefix'} renderSuffix={() => 'Suffix'} /> </div>

<div style={{ display: 'grid', gridGap: '1rem' }}>
    <TextField
        renderStartAddOn={() => <InputGroup.Text>Start AddOn</InputGroup.Text>}
        renderEndAddOn={() => <InputGroup.Text>End AddOn</InputGroup.Text>}
        renderPrefix={() => 'Prefix'}
        renderSuffix={() => 'Suffix'}
    />
    <TextField
        renderStartAddOn={() => <Button variant="outline-secondary">Start AddOn</Button>}
        renderEndAddOn={() => <Button variant="outline-secondary">End AddOn</Button>}
        renderPrefix={() => 'Prefix'}
        renderSuffix={() => 'Suffix'}
    />

    <TextField
        renderStartAddOn={() => (
            <DropdownButton title="Start AddOn" variant="outline-secondary">
                <DropdownItem>Item</DropdownItem>
            </DropdownButton>
        )}
        renderEndAddOn={() => (
            <DropdownButton title="End AddOn" variant="outline-secondary">
                <DropdownItem>Item</DropdownItem>
            </DropdownButton>
        )}
        renderPrefix={() => 'Prefix'}
        renderSuffix={() => 'Suffix'}
    />
</div>

Multiple prefixes or suffixes

Some field components (e.g. NumberField) utilize prefixes or suffixes to display controls like the plus and minus spinner. In these cases it may be necessary to set the flex order of your prefix/suffix to make sure it's displayed correctly.

Result

Loading...

Live Editor

<NumberField renderSuffix={() => <span className="order-first me-2">USD</span>} />

<NumberField
    renderSuffix={() => <span className="order-first me-2">USD</span>}
/>

Sizes

The size prop can be used to change the size of the field. The default size is md.

Result

Loading...

Live Editor

<div style={{ display: 'grid', gridGap: '1rem', }} > <TextField renderStartAddOn={() => <InputGroup.Text>Start</InputGroup.Text>} renderEndAddOn={() => <InputGroup.Text>End</InputGroup.Text>} renderPrefix={() => 'Prefix'} renderSuffix={() => 'Suffix'} size="sm" value="Small" /> <TextField renderStartAddOn={() => <InputGroup.Text>Start</InputGroup.Text>} renderEndAddOn={() => <InputGroup.Text>End</InputGroup.Text>} renderPrefix={() => 'Prefix'} renderSuffix={() => 'Suffix'} value="Medium (default)" /> <TextField renderStartAddOn={() => <InputGroup.Text>Start</InputGroup.Text>} renderEndAddOn={() => <InputGroup.Text>End</InputGroup.Text>} renderPrefix={() => 'Prefix'} renderSuffix={() => 'Suffix'} size="lg" value="Large" /> </div>

<div
    style={{
        display: 'grid',
        gridGap: '1rem',
    }}
>
    <TextField
        renderStartAddOn={() => <InputGroup.Text>Start</InputGroup.Text>}
        renderEndAddOn={() => <InputGroup.Text>End</InputGroup.Text>}
        renderPrefix={() => 'Prefix'}
        renderSuffix={() => 'Suffix'}
        size="sm"
        value="Small"
    />
    <TextField
        renderStartAddOn={() => <InputGroup.Text>Start</InputGroup.Text>}
        renderEndAddOn={() => <InputGroup.Text>End</InputGroup.Text>}
        renderPrefix={() => 'Prefix'}
        renderSuffix={() => 'Suffix'}
        value="Medium (default)"
    />
    <TextField
        renderStartAddOn={() => <InputGroup.Text>Start</InputGroup.Text>}
        renderEndAddOn={() => <InputGroup.Text>End</InputGroup.Text>}
        renderPrefix={() => 'Prefix'}
        renderSuffix={() => 'Suffix'}
        size="lg"
        value="Large"
    />
</div>

Radii

The radius prop can control the corner styling of any field component. The default is round. The other options are square and pill.

Result

Loading...

Live Editor

<div style={{ display: 'grid', gridGap: '1rem', }} > <TextField renderStartAddOn={() => <InputGroup.Text>Start</InputGroup.Text>} renderEndAddOn={() => <InputGroup.Text>End</InputGroup.Text>} renderPrefix={() => 'Prefix'} renderSuffix={() => 'Suffix'} radius="square" value="Square" /> <TextField renderStartAddOn={() => <InputGroup.Text>Start</InputGroup.Text>} renderEndAddOn={() => <InputGroup.Text>End</InputGroup.Text>} renderPrefix={() => 'Prefix'} renderSuffix={() => 'Suffix'} value="Round (default)" /> <TextField renderStartAddOn={() => <InputGroup.Text>Start</InputGroup.Text>} renderEndAddOn={() => <InputGroup.Text>End</InputGroup.Text>} renderPrefix={() => 'Prefix'} renderSuffix={() => 'Suffix'} radius="pill" value="Pill" /> </div>

<div
    style={{
        display: 'grid',
        gridGap: '1rem',
    }}
>
    <TextField
        renderStartAddOn={() => <InputGroup.Text>Start</InputGroup.Text>}
        renderEndAddOn={() => <InputGroup.Text>End</InputGroup.Text>}
        renderPrefix={() => 'Prefix'}
        renderSuffix={() => 'Suffix'}
        radius="square"
        value="Square"
    />
    <TextField
        renderStartAddOn={() => <InputGroup.Text>Start</InputGroup.Text>}
        renderEndAddOn={() => <InputGroup.Text>End</InputGroup.Text>}
        renderPrefix={() => 'Prefix'}
        renderSuffix={() => 'Suffix'}
        value="Round (default)"
    />
    <TextField
        renderStartAddOn={() => <InputGroup.Text>Start</InputGroup.Text>}
        renderEndAddOn={() => <InputGroup.Text>End</InputGroup.Text>}
        renderPrefix={() => 'Prefix'}
        renderSuffix={() => 'Suffix'}
        radius="pill"
        value="Pill"
    />
</div>

Usage

Form Component

If you need more control over how the form inputs are rendered (E.g. columns or other custom layouts) you can use the individual form components inside of a Kyber Form component. The Form component will still help you manage state and validation while you have direct access to each input component.

Result

Loading...

Live Editor

<Form validationSchema={object().shape({ name: string().required().label('Name'), age: number().required().label('Age'), })} onSubmit={(values, actions) => { actions.setSubmitting(false); }} > <FormField> <TextField label="Name" name="name" /> </FormField> <FormField> <NumberField label="Age" name="age" /> </FormField> </Form>

<Form
    validationSchema={object().shape({
        name: string().required().label('Name'),
        age: number().required().label('Age'),
    })}
    onSubmit={(values, actions) => {
        actions.setSubmitting(false);
    }}
>
    <FormField>
        <TextField label="Name" name="name" />
    </FormField>

    <FormField>
        <NumberField label="Age" name="age" />
    </FormField>
</Form>

DataForm Component

If your form is straightforward you can build it using just the DataForm component and an object based schema.

DataForm is only available in the @emoney/kyber-forms package.

Result

Loading...

Live Editor

const schema = object().shape({ name: string().required().label('Name'), age: number().required().label('Age'), }); render( <DataForm id="dataform" validationSchema={schema} fields={[ { as: 'TextField', name: 'name', fieldLabel: 'Name' }, { as: 'NumberField', name: 'age', fieldLabel: 'Age' }, ]} onSubmit={(values, actions) => { actions.setSubmitting(false); console.log({ values }); }} />, );

const schema = object().shape({
    name: string().required().label('Name'),
    age: number().required().label('Age'),
});

render(
    <DataForm
        id="dataform"
        validationSchema={schema}
        fields={[
            { as: 'TextField', name: 'name', fieldLabel: 'Name' },
            { as: 'NumberField', name: 'age', fieldLabel: 'Age' },
        ]}
        onSubmit={(values, actions) => {
            actions.setSubmitting(false);

            console.log({ values });
        }}
    />,
);

Self Managed

If you need complete control over the form you can manage state and validation yourself by importing the individual form components and combining them with third party form management and validation libraries. The Kyber team recommends Formik and Yup, but other libraries like React Hook Form can also work.

Note: This example uses the HTML <form> element, not the Kyber Form component.

Result

Loading...

Live Editor

setLocale(yupValidation); const schema = object().shape({ name: string().required().label('Name'), age: number().required().label('Age'), }); function Example() { const { values, touched, errors, setFieldValue, handleBlur, handleSubmit } = useFormik({ initialValues: { name: '', age: '', }, onSubmit: (values) => { console.log(values); }, validationSchema: schema, }); const handleChange = (name) => (value) => { setFieldValue(name, value); }; return ( <form onSubmit={handleSubmit}> <TextField errorText={errors.name} isInvalid={touched.name && errors.name} label="Name" name="name" onBlur={handleBlur} onChange={handleChange('name')} value={values.name} /> <NumberField errorText={errors.age} isInvalid={touched.age && errors.age} label="Age" name="age" onBlur={handleBlur} onChange={handleChange('age')} value={values.age} /> <Button className="mt-3" id="form-submit" type="submit" primary> Submit </Button> </form> ); } render(<Example />);

setLocale(yupValidation);

const schema = object().shape({
    name: string().required().label('Name'),
    age: number().required().label('Age'),
});

function Example() {
    const { values, touched, errors, setFieldValue, handleBlur, handleSubmit } = useFormik({
        initialValues: {
            name: '',
            age: '',
        },
        onSubmit: (values) => {
            console.log(values);
        },
        validationSchema: schema,
    });

    const handleChange = (name) => (value) => {
        setFieldValue(name, value);
    };

    return (
        <form onSubmit={handleSubmit}>
            <TextField
                errorText={errors.name}
                isInvalid={touched.name && errors.name}
                label="Name"
                name="name"
                onBlur={handleBlur}
                onChange={handleChange('name')}
                value={values.name}
            />
            <NumberField
                errorText={errors.age}
                isInvalid={touched.age && errors.age}
                label="Age"
                name="age"
                onBlur={handleBlur}
                onChange={handleChange('age')}
                value={values.age}
            />
            <Button className="mt-3" id="form-submit" type="submit" primary>
                Submit
            </Button>
        </form>
    );
}

render(<Example />);