Newskit Logo

Getting started

Design overview

Popular searches

View GitHub

Actions & Inputs

Form

Forms let users enter and edit information using form controls. Based on React Hook Form.

Status

Supported

Introduced

v0.19.0

View codeView Storybook

Interactive demo

This demo lets you preview the form component, its variations and configuration options.

Validation Mode
ReValidation Mode
1import React from 'react';
2import { Form } from 'newskit';
3
4export default () => <Form />;
5

Anatomy

Form

The form component contains two required elements and no optional elements.

ItemNameDescriptionComponentOptional

Form input components

These are the form input components available for use with the form:

ItemNameDescriptionComponentOptional

Options

Form input components have options for different use cases:

FormInputLabel

When wrapped inside the FormInput component, the state can be passed down to the FormInputLabel component if the user desires.

Note

Ensure screen readers can read labels by setting the aria-label attribute to the label text’s value.

FormInputAssistiveText

When wrapped inside the FormInput, the state can be passed down to theFormInputAssistiveText component, depending on if validation is a success or error state.

FormInputAssistiveText can also display a character count to let users know how much text they can enter, when there is a limit set on the number of characters on a text field or text area.

FormInputTextArea

When wrapped inside the FormInput the state can be passed down to the FormInputTextField component, depending on if validation is a success or error state. Text area documentation.

FormInputTextField

When wrapped inside the FormInput the state can be passed down to the FormInputTextField component, depending on if validation is a success or error state. Text field documentation.

FormInputSelect

When wrapped inside the FormInput the state can be passed down to the FormInputSelect component, depending on if validation is a success or error state. Select documentation.

FormInputCheckbox

When wrapped inside the FormInput the state can be passed down to theFormInputCheckbox component, depending on if validation is a success or error state. Checkbox documentation.

FormInputRadioButton

When wrapped inside the FormInput the state can be passed down to theFormInputRadioButton component, depending on if validation is a success or error state. Multiple can be grouped together using the radioGroup component. Radio Button documentation.

Fieldset

Selection controls (inputs), such as the FormInputRadioButton, andFormInputCheckbox, can be grouped together with other selection controls, labels and assistive text together in a fieldset. The fieldset has a caption that gives a title attributed to the elements that appear in the fieldset, called a legend. Fieldset documentation.

FormInputLabel

When wrapped inside the FormInput component, the state can be passed down to the FormInputLabel component if the user desires.

Note

Ensure screen readers can read labels by setting the aria-label attribute to the label text’s value.

FormInputAssistiveText

When wrapped inside the FormInput, the state can be passed down to theFormInputAssistiveText component, depending on if validation is a success or error state.

FormInputAssistiveText can also display a character count to let users know how much text they can enter, when there is a limit set on the number of characters on a text field or text area.

FormInputTextArea

When wrapped inside the FormInput the state can be passed down to the FormInputTextField component, depending on if validation is a success or error state. Text area documentation.

FormInputTextField

When wrapped inside the FormInput the state can be passed down to the FormInputTextField component, depending on if validation is a success or error state. Text field documentation.

FormInputSelect

When wrapped inside the FormInput the state can be passed down to the FormInputSelect component, depending on if validation is a success or error state. Select documentation.

FormInputCheckbox

When wrapped inside the FormInput the state can be passed down to theFormInputCheckbox component, depending on if validation is a success or error state. Checkbox documentation.

FormInputRadioButton

When wrapped inside the FormInput the state can be passed down to theFormInputRadioButton component, depending on if validation is a success or error state. Multiple can be grouped together using the radioGroup component. Radio Button documentation.

Fieldset

Selection controls (inputs), such as the FormInputRadioButton, andFormInputCheckbox, can be grouped together with other selection controls, labels and assistive text together in a fieldset. The fieldset has a caption that gives a title attributed to the elements that appear in the fieldset, called a legend. Fieldset documentation.

Behaviours

Here’s how the form input components behave:

Form input validation

Define FormInput validation rules for onSubmit or onBlur, for both the initial validation and re-validation using the form. Learn more about validation rules with React Hook Form.

For validation to work, you need to individually wrap each form input component (e.g. FormInputTextField) in the form component. For example:

1<Form onSubmit={onSubmit}>
2  <FormInput
3    name="checkbox"   
4    rules={{
5      required: 'Required field',
6    }}
7  >
8    <FormInputCheckbox value="tc" />
9  </FormInput> 
10  <FormInput
11        name="select"
12        rules={{
13          required: 'Required field',
14        }}
15      >
16    <FormInputSelect>
17      <SelectOption value="Option 1">Option 1</SelectOption>
18      <SelectOption value="Option 2">Option 2</SelectOption>
19    </FormInputSelect>
20  </FormInput>
21  <Button type="submit">Submit</Button>
22</Form>



Form yup schema

The form supports schema validation with external validation libraries. To use Yup, for example, pass yupResolver(schema)to the resolver prop. Learn more about schema validation with React Hook Form.

1import {yupResolver} from '@hookform/resolvers/yup';
2import * as yup from 'yup';
3
4const schema = yup.object().shape({
5  email: yup.string().email().required(),
6  username: yup.string().required(),
7});
8
9<Form onSubmit={onSubmit} resolver={yupResolver(schema)}>
10  <FormInput name="email">
11    <FormInputLabel>E-mail</FormInputLabel>
12    <FormInputTextField type="email" />
13    <FormInputAssistiveText>Enter your email</FormInputAssistiveText>
14  </FormInput>
15  <FormInput name="username">
16    <FormInputLabel>Username</FormInputLabel>
17    <FormInputTextField />
18    <FormInputAssistiveText>Enter username</FormInputAssistiveText>
19  </FormInput>
20  <Button type="submit">
21    Submit
22  </Button>
23</Form>;
24

Assistive text minimum height

Apply a minimum height to the assistive text container to stop the layout of the page shifting when the assistive text shows and hides.

Assistive text overflow wrap

When the assistive text is too long for the available horizontal space, it wraps to form another line.

Assistive text minimum height

Apply a minimum height to the assistive text container to stop the layout of the page shifting when the assistive text shows and hides.

Assistive text overflow wrap

When the assistive text is too long for the available horizontal space, it wraps to form another line.

Usage

Here’s how and when to use the form:

For best practices to follow when creating a form, see the forms patterns guidance.

Do keep forms clear and simple

Clear, simple forms help prevent users from getting confused and submitting wrong information.

Don't include questions that aren't essential

Ask yourself if each FormInput is necessary.

Do wrap FormInput components that need validation

Ensure each FormInput component that needs validation is wrapped in a form.

Don’t validate prematurely

Avoid prematurely validating a FormInput (e.g. avoid setting text fields to invalid before the user has finished typing).

Do use onBlur validation

Where possible, validate using onBlur (i.e. when the user clicks out of a FormInput, it’s validated).

Do make error text clear and helpful

Error text should be clear, concise and written in complete sentences - and it should tell the user how to resolve the issue.

Do use sentence case for labels and assistive text

Write labels and assistive text in sentence case to help with scannability and legibility.

Don't truncate or wrap labels

Keep labels short, clear and fully visible.

Do keep labels and assistive text close to FormInput

Labels and assistive text should be in close proximity to their FormInput components to provide context for users.

Do use assistive text for instructions

Use assistive text for instructions on completing an input or to communicate requirements.

Do swap assistive text with error text or character count

Swap assistive text with error text or character count as required. Once the input is valid, show the assistive text or character count again.

Do nest FormInput components

FormInput components don't need to be direct children of the form component and can be nested inside other elements.

Tutorial

Learn how to use the form component effectively using the tutorial below.

Form tutorial

Tutorial for engineers to build a form using the form sub components.

Tutorial for engineers to build a form using the form sub components.

Form structure

This diagram shows how to use form input components inside a fieldset, which you can then use to create a full form:

Accessibility considerations

The form has the following accessibility considerations:

Keyboard Interactions
CommandDescription
WAI-ARIA
ElementAttributeValueDescriptionUser supplied

API

Form

The form has a range of props to define the experience in different use cases.

NameTypeDefaultDescriptionRequired
Form input

The form input has a range of props to define the experience in different use cases.

NameTypeDefaultDescriptionRequired
Form input assistive text

The FormInputAssistiveText component has a range of props to define the experience in different use cases. Use within the form component.`,

NameTypeDefaultDescriptionRequired

Note

Props and overrides for the assistive text component are the same as the form input assistive text component, as listed above.

Form input label

The FormInputLabel has a range of props to define the experience in different use cases. Use within the form.

NameTypeDefaultDescriptionRequired

Note

Props and overrides for the label component are the same as the FormInputLabel component, as listed above. For details of props and overrides:
  • FormInputTextField

Need Help?

Cant find what you are looking for?

Get In Touch

Need Help?

Cant find what you are looking for?