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
npm install @nib-components/form-control
Note: You will also need to install the peerDependencies @nib/icons and @nib-components/theme.
Usage
import FormControl from '@nib-components/form-control';
Interactive demo
FullStoryMask
FormControl also exports a utility for masking elements within FullStory recordings.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
id (required) | string | An id for the underlying input, and used as the for attribute on the label. For consistency we use slug notation for ids. | |
label (required) | string | A label displayed to the user. All inputs must have a label for improved a11y. | |
name | string | The name of the control. For consistency we use camelCase notation for names. | |
help | string | Extra supporting text for the field. | |
error | string | An error displayed to the user. The error is displayed if set to any non-empty string. | |
info | string | An informational message displayed to the user when a field is valid. The message is displayed if set to any non-empty string. | |
width | number or string | The 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%". | |
inline | boolean | true | Only for FieldsetFormControl components. Set to false to keep radios/checkboxes stacked above the sm breakpoint. |
validated | boolean | Whether the control has been validated. Usually you want to set this if the user has interacted and left the field, or on form submit. | |
valid | boolean | Whether the value(s) within the control are valid. | |
disabled | boolean | false | Whether the FormControl and its underlying input should be disabled. |
hasNegativeFieldsetMargin | boolean | true | Only for FieldsetFormControl components. Remove margin-bottom from radios/checkboxes for styling within Form components. |
isEmptyAndOptional | boolean | false | When true, the validation icon will be hidden and the field will not be required within a form. |
formMode (deprecated) | string | Defined by the theme | Can be one of "white" or "light". Mode support has been shifted to the ModeProvider component instead of here. |
formControlType | string | This 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". | |
fullstory | string | "mask" | One of "exclude", "mask", or "unmask". Applied to the input and the info message. See help.fullstory.com for more information. |
children | element | The form input wrapped by this component. | |
isFullWidthSelect | boolean | false | Whether 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
| Prop | Type | Default | Description |
|---|---|---|---|
inline | boolean | false | Whether to render a span or a div. |
level | string | mask | One 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.