Stable

Textbox

Use a textbox when the expected user input is a single line of text. They are commonly used in forms.

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

Installation

bash

npm install @nib-components/textbox

As a form input, @nib-components/form-control must wrap this component to provide an accessible label, help text, and validation styling.

Usage

jsx

import Textbox from '@nib-components/textbox';

Interactive demo

jsx

<FormControl id="first-name" name="firstName" label="What's your name?" help="As it appears on your passport" valid={false} validated={false} error="Please enter your first name.">
  <Textbox />
</FormControl>

<FormControl id="first-name" name="firstName" label="What's your name?" help="As it appears on your passport" valid={false} validated={false} error="Please enter your first name.">
  <Textbox />
</FormControl>

Props

As the <Textbox/> is wrapped in a <FormControl/>, all FormControl props such as valid, validated, and disabled will be passed down to this component. This includes the id, name and label which will align with the for attribute on the <label>.

All props passed directly to <Textbox/> will be applied to the underlying <input> as attributes.

Labels

Labels help the user understand what information to enter into the textbox field. Labels are short, concise and use sentence-style capitalisation.

Optional inputs

Denote optional fields by adding “(Optional)" to the end of the textbox label.

Label (Optional)

Accessibility best practices for labels

Labels must be visible when a textbox is in focus.
Labels must be announced to the screen reader on focus.

Placeholder text

Avoid using placeholder text in textboxes. Placeholder text is not accessible due to low colour contrast and the disappearing placeholder text requires the user to rely on their short-term memory to complete the field correctly. Placeholder text can also be mistaken as a default value causing the user to skip the field completely.

Help text should be used in place of placeholder text to communicate supporting instructions.

Help text

Help text is an instruction that supports a user to fill out a textbox field. It can also be used to clarify how the information will be used. It is optional and should only be used where needed.

Help text should appear below the label and above the textbox field. Use sentence-style capitalisation and concise sentence/s.

Accessibility best practices for help text

Help text displayed above the textbox field allows screen readers to read the help information before the user completes a field.

Text input length

On desktop and tablet screens the length of the textbox should reflect the expected amount of information to be provided. This visual cue gives the user a hint as to how much text to enter.

On mobile the textbox should be full width. This supports users to easily tap the textbox from either side of the mobile device.

Autocomplete

The autocomplete attribute allows the textbox to autofill information on the user’s behalf if they've entered it previously. The value of this attribute is specific to the use-case of the textbox. In React, we must use the camelCase variant autoComplete.

For example, the autoComplete value for an email address textbox is “email”:

jsx

<FormControl id="email" name="email" help="Please enter your email address." label="What's your email?">
  <Textbox autoComplete="email" />
</FormControl>

For a list of valid autocomplete values, refer to this HTML autocomplete attribute resource.

Validation and errors

Textbox validation should happen in real-time so the user can fix input errors when they occur. The success state should appear when the input is valid and the error state should appear when the input is invalid.

The success state is denoted with a green border on the bottom of the textbox field and a green success icon.

Email address

The error state is denoted with a red border, a red error icon and a red error message below the textbox field. A good error message clearly describes how to address the input error. The error state only appears when the user clicks/taps away from the textbox field. Once the user corrects the textbox input error, the error state is replaced with the success state.