Stable

Form

The form component is a simple styled container for our form controls. Forms should be used to collect simple data from our users. Users should be able to complete forms quickly and without confusion.

GitHub, opens in a new tab·Storybook, opens in a new tab·Playroom, opens in a new tab

Installation

bash

npm install @nib-components/form

Usage

jsx

import Form from '@nib-components/form';

Interactive demo

jsx

<Form id="exampleForm" name="exampleForm" title="Raise an issue" subtitle="We try to reply to all issues within two business days." formType="required">
  <FormControl id="firstName" name="firstName" label="What is your name" help="We just need your first name.">
    <Textbox />
  </FormControl>
  <FormControl id="description" name="description" label="Describe your issue" help="Be as specific as you can.">
    <Textarea rows="4" />
  </FormControl>
  <FormControl id="customer" name="customer" label="Are you an nib customer?" error="Please select whether you are a customer or not">
    <RadioGroup
      options={{
        no: 'No',
        yes: 'Yes'
      }}
    />
  </FormControl>
  <FormControl id="human" name="human" label="Are you human?">
    <Checkbox label="I am human" value="confirm" />
  </FormControl>
  <PrimaryButton type="submit">Submit</PrimaryButton>
</Form>

Props

Prop	Type	Default	Description
`id` (required)	string		The `form` id.
`name` (required)	string		The `form` name.
`title`	string		The `form` title.
`titleComponent`	string	`'h3'`	The underlying component of the Form `title`. Must be one of `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `div`, `label`, `span`, `header`.
`subtitle`	string \| ReactNode		Subtitle to be shown below the title.
`containerWidth`	string	`'768px'`	The form will render with a width of 100%, with an internal container to house the fields. This prop controls the width of this internal container. To disable, set to `null`.
`mode`	string or object		The mode to use. For more information, see the Box component docs.
`foreground`	string	`'default'`	The foreground color of the Form. For more information, see the Box component docs.
`background`	string	`'default'`	The background color of the Form. For more information, see the Box component docs.
`padding`	number or object	`{xs: 4, sm: 6}`	A size from our spacing scale. For more information, see the Box component docs.
`borderRadius`	string	`'none'`	The border radius of the Form. For more information, see the Box component docs.
`spaceChildren`	boolean	`true`	Whether or not to apply consistent spacing to all direct children of the form. You may choose to opt-out to customise the layout yourself.
`onSubmit`	function		The function to call on form submission.
`isCompact`	boolean	`false`	Add compact styles to all child form components. All form fields will be horizontally placed in a flexbox. This should only be used for internal/dashboard/portal style applications.
`formType`	string		This property determines if all the fields in the form is required or optional. Additionally, it will display the info message according to the prop value. Must be one of `"optional"` or `"required"`.
`hideFormTypeMessage`	boolean	`false`	This prop helps to hide/show the `formType` info message.

Styling

Because the Form comes with built-in styling (padding, backgrounds, containerWidth etc.), you may need to opt-out of some styling when rendering within an existing layout.

jsx

<Form
  // snip
  padding={0}
  spaceChildren={false}
  containerWidth="unset"
  // snip
/>

Considerations

Forms are best used for simple data gathering and are to be avoided for complex interactions.

It is good practice to include a title for the form. This will provide further clarity about the context of data being gathered.

Use informative error messages as this will help the user to correct any information entered incorrectly.

Independent field validation is prefered for providing clearer and faster feedback to the user so that they are able to complete their goal faster.

We recommend not prefilling fields with placeholder text. Users can mistakenly think they have filled out the field and can also be frustrated when placeholders disappear once the field is entered.

The formType prop specifies whether all input fields are required or optional. This prop not only displays an informational message beneath the form title but also controld the aria-required attribute on the input fields. If the formControlType prop is set on an input field, it overrides the formType prop to determine the aria-required attribute.

Form Control

Edit this page