Text input

import { ... } from '@ag.ds-next/react/text-input';

<TextInput label="Name" />

By default, the TextInput component does not expand to fill the available space.

Do

• use when unique information needs to be entered that can’t be answered through preset options
• indicate if input is optional
• provide useful hints where necessary
• provide an error message when input is invalid
• align form inputs using a Form stack
• hide the ‘optional’ label when filtering data.

Don’t

• use if a dropdown, select, or radio button can be used instead
• use for passwords - use Password input instead
• hide the ‘optional’ label within a form
• use placeholder text as a substitute for a label.

Hint

Use the hint prop to provide help that’s relevant to the majority of users, like how their information will be used, or where to find it.

Don’t use long paragraphs and lists in hint text. Screen readers read out the entire text when users interact with the form element. This could frustrate users if the text is long.

Don’t include links within hint text. While screen readers will read out the link text when describing the field, they will not tell users that the text is a link.

<TextInput label="Name" hint="Hint text" />

Required

The required prop can be used to indicate that user input is required on the field before a form can be submitted.

Required fields do not append ‘(optional)’ to the label and also use aria-required to indicate to screen readers that the field is required.

Hide optional label

The hideOptionalLabel prop can be used in situations where you want to indicate to screen reader users that a field is optional but don’t want to show the ‘(optional)’ label.

The usage of hideOptionalLabel should be reserved for inputs that filter data in a table or chart, and should never be used in standard forms for submitting information.

<Stack gap={1}>
	<TextInput label="Required" required />
	<TextInput label="Optional" required={false} />
	<TextInput
		label="Optional with hideOptionalLabel"
		required={false}
		hideOptionalLabel={true}
	/>
</Stack>

Invalid

Use the invalid prop to indicate if the user input is invalid.

<TextInput label="Invalid" invalid message="This input is invalid" />

Disabled

Disabled input elements are unusable and can not be clicked. This prevents a user from interacting with the input element until another action is complete. Disabled input elements in a form will not be submitted.

<TextInput label="Name" disabled />

Maximum widths

The width of a text input field should indicate the amount of information expected to be entered into the field. The size of the text input acts as a visual constraint for the end user.

As an example, input fields for postcodes should have a smaller width than fields for emails.

<Stack gap={1}>
	<TextInput label="xs input" maxWidth="xs" />
	<TextInput label="sm input" maxWidth="sm" />
	<TextInput label="md input" maxWidth="md" />
	<TextInput label="lg input" maxWidth="lg" />
	<TextInput label="xl input" maxWidth="xl" />
</Stack>

Block

Use the block prop to expand the component to fill the available space.

<TextInput label="Name" block />

Related components

• Autocomplete – Autocomplete, also known as type-ahead, uses predictive text to help select options as a user types.
• Combobox – This component allows users to select from a list of options. It’s especially useful when there are many options to choose from.
• Password input – The password input component allows users to securely enter a password. The text is obscured by default, but can be revealed by pressing the ‘Show password’ checkbox.
• Textarea – A text area lets users enter long-form, plain text over multiple lines and is commonly found in forms.