Design Tokens for Mesh have just been released!
Skip to content

Form Control

A form control is a combination of a form field, a label, a hint and form validation. All form components must be wrapped in a form control.

Installation

bash
npm install @nib-components/form-control

Note: You will also need to install the peerDependencies @nib/icons and @nib-components/theme.

Usage

jsx
import FormControl from '@nib-components/form-control';

Interactive demo

jsx

FullStoryMask

FormControl also exports a utility for masking elements within FullStory recordings.

jsx
import {FullStoryMask} from '@nib-components/form-control';
<Copy>
Your address is <FullStoryMask inline>1234 Sesame Street</FullStoryMask>
</Copy>;

Props

FormControl

The <FormControl /> will pass down these props to the underlying child components.

PropTypeDefaultDescription
id (required)stringAn id for the underlying input, and used as the for attribute on the label. For consistency we use slug notation for ids.
label (required)stringA label displayed to the user. All inputs must have a label for improved a11y.
namestringThe name of the control. For consistency we use camelCase notation for names.
helpstringExtra supporting text for the field.
errorstringAn error displayed to the user. The error is displayed if set to any non-empty string.
infostringAn informational message displayed to the user when a field is valid. The message is displayed if set to any non-empty string.
widthnumber or stringThe width for the input based upon the number of characters expected. For example an australian post code would only ever be 4 digits, so a width={4} should be applied. It can also be a string representing the percentage of it's container, for example width="50%".
inlinebooleantrueOnly for FieldsetFormControl components. Set to false to keep radios/checkboxes stacked above the sm breakpoint.
validatedbooleanWhether the control has been validated. Usually you want to set this if the user has interacted and left the field, or on form submit.
validbooleanWhether the value(s) within the control are valid.
disabledbooleanfalseWhether the FormControl and its underlying input should be disabled.
hasNegativeFieldsetMarginbooleantrueOnly for FieldsetFormControl components. Remove margin-bottom from radios/checkboxes for styling within Form components.
isEmptyAndOptionalbooleanfalseWhen true, the validation icon will be hidden and the field will not be required within a form.
formMode (deprecated)stringDefined by the themeCan be one of "white" or "light". Mode support has been shifted to the ModeProvider component instead of here.
formControlTypestringThis property determines if the field is required or optional. It will specify whether to render an Optional or Required tag, and it controls the aria-required attribute accordingly. Must be one of "optional" or "required".
fullstorystring"mask"One of "exclude", "mask", or "unmask". Applied to the input and the info message. See help.fullstory.com for more information.
childrenelementThe form input wrapped by this component.
isFullWidthSelectbooleanfalseWhether to set max-width to 100%. By default, Select components have space allocated to the right for a validation icon to appear. This prop turns off this space and should only be used when the select input is not going to be validated.

FullStoryMask

PropTypeDefaultDescription
inlinebooleanfalseWhether to render a span or a div.
levelstringmaskOne of "exclude", "mask", or "unmask". See help.fullstory.com for more information.

Validation and errors

If both valid and validated props are true, the control will be styled with a validation tick. If valid is false and validated is set, it will be styled as a validation error.

Considerations

Labels should be positioned above the field input and be keep short and clear.

Keep hints outside the field so the user can still read them when they type.

Human friendly words work best in labels (not always the label from the database).

Validation errors should be removed when the user has entered valid input.

If validation occurs on submit always return to the first error and highlight the error message.

The form input should be of equal length (where possible) to valid user input.

Setting the width of a form control

The width prop represents a max-width for the wrapper around the input. It is helpful for the user when the textbox hints at the number of characters expected to be entered. For example an Australian post code would only ever be 4 digits, so should have a shorter input than a field requesting the user's email address.

The width can be set to a number if the expected data is of known length (E.g. width={4} for the Australian postcode). This is mapped back to character widths. Otherwise width accepts any css width value string: '50%', '20rem', '500px', etc.

If not set, inputs are full-width.