Field

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

The field component connects the label, description and message to the input element.

<Field label="Name">{(a11yProps) => <input {...a11yProps} />}</Field>

Label

Each field must be accompanied by a label. Effective form labeling helps users understand what information to enter into the input.

<Field label="Name">{(a11yProps) => <input {...a11yProps} />}</Field>

Hint

Use the hint prop to provide help that’s relevant to the majority of users, like the required format of the input, 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.

<Field label="Email" hint="We will only use this to respond to your question">
	{(a11yProps) => <input type="email" {...a11yProps} />}
</Field>

Invalid

Error messages are used to notify the user when a form field has not passed validation. Use clear messages to explain what went wrong and how to fix it.

<Field
	label="Email"
	invalid
	message="Enter an email address in the correct format, like name@example.com"
>
	{(a11yProps) => <input type="email" {...a11yProps} />}
</Field>

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}>
	<Field label="Required" required={true}>
		{(a11yProps) => <input {...a11yProps} />}
	</Field>
	<Field label="Optional" required={false}>
		{(a11yProps) => <input {...a11yProps} />}
	</Field>
	<Field
		label="Optional with hideOptionalLabel"
		required={false}
		hideOptionalLabel={true}
	>
		{(a11yProps) => <input {...a11yProps} />}
	</Field>
</Stack>

Hooks

useScrollToField

useScrollToField is a hook that can be used to scroll and focus users to a form field on the same page.

Because our labels or legends appear above the input, when using native browsers APIs, users will be presented with an input without any context, as the label or legend will be off the top of the screen. Manually handling the click event, scrolling the question into view and then focusing the element solves this.

Please refer to the example site single-page form example to see an example of this hook in use.

/**
 * Example usage when displaying a list of form validation errors
 */
function ExampleOne() {
	const scrollToField = useScrollToField();
	return (
		<ul>
			{Object.entries(errors).map(([id, errorMessage]) => (
				<li key={id}>
					<a href={`#${id}`} onClick={scrollToField}>
						{errorMessage}
					</a>
				</li>
			))}
		</ul>
	);
}

/**
 * Example usage scrolling and focusing to a specific field on first mount
 */
function ExampleTwo() {
	const targetId = 'last-name'; // This could potentially come from route query params
	const scrollToField = useScrollToField();

	React.useEffect(() => {
		scrollToField(targetId);
	}, [scrollToField]);

	return (
		<FormStack>
			<TextInput label="First name" id="first-name" />
			<TextInput label="Last name" id="last-name" />
		</FormStack>
	);
}

Related components

• Fieldset – The Fieldset component is used to group related form fields and includes a descriptive legend to label the group, helping users understand the relationship between these form fields.

Related patterns

• Messaging – Messaging conveys contextual information to the user, provides information in relation to a service or interaction, and provides feedback in response to their actions or the current system status.