Page alert

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

Typically page alerts appear at the top of a page following a submit action.

Do

• place the Page alert component near the top of the page, under the H1 and introductory paragraph, when validating forms and focus immediately after a submission attempt
• use constructive, no-blame language, avoid vague descriptions and always provide a solution
• keep it short – content should be understood at a glance
• use the correct colour tone for the message (see tones below)

Don’t

• insert a Page alert into a Hero category banner, instead position the page alert after the h1
• repeat the title in the description
• if the alert title is enough to convey the message, a description may not be necessary
• use for common actions such as deleting an email or tasks where an action can be undone
• use for information unrelated to the specific journey
• use in a form with only one input error - assign focus to the input where the error occurred
• include a close button for error messages.

Tones

Choosing a tone for a PageAlert allows the user to understand the importance and severity of the message at a glance.

The four supported tones are info, success, error and warning.

Info

The information page alert (blue) is used to highlight important information to the user before they move on. Info alerts should be used sparingly.

<PageAlert tone="info" title="Notice">
	<Text as="p">
		All vacancies close on the advertised closing date unless otherwise
		specified.
	</Text>
</PageAlert>

Success

The success page alert (green) is used for notifying the user that a task is fully completed.

<PageAlert tone="success" title="Submission successful">
	<Text as="p">Your application has been successfully submitted.</Text>
</PageAlert>

Error

The error page alert (red) should be used with form validation errors or other errors which the user must action before they can can continue.

<PageAlert tone="error" title="There is a problem">
	<Text as="p">Please correct the following fields and try again</Text>
	<UnorderedList>
		<ListItem>
			<TextLink href="#">Full name must not be empty</TextLink>
		</ListItem>
		<ListItem>
			<TextLink href="#">Email must not be empty</TextLink>
		</ListItem>
	</UnorderedList>
</PageAlert>

Warning

Use warning page alerts (orange) to tell the user how to avoid a problem. Only use an alert if the information will help the user avoid a problem.

<PageAlert tone="warning" title="Browser out of date">
	<Text as="p">Your web browser is out of date.</Text>
</PageAlert>

Dismissable

Page alerts can be dismissed by a user if they have understood the message and no longer need to see it.

Use the onClose prop to make the alert dismissable. Ensure Page alerts that are closed by the user are never seen again. You could do this through a feature flag in a database, or by setting a value in the browser.

When a user dismisses an alert, it’s important to manage their focus appropriately to help them continue their task or journey. In some cases, there may not be an obvious (or any) element to send focus to, such as when the alert was triggered by an action on a previous page or from a drawer that is now closed. Always carefully consider the context and previous user actions before moving their focus to ensure a smooth and accessible experience.

<PageAlert tone="info" title="New update" onClose={console.log}>
	<Text as="p">
		A new feature has been added to the service.{' '}
		<TextLink href="#">Learn more</TextLink>.
	</Text>
</PageAlert>

Focusing the alert

NOTE: When focusing an alert after closing a Drawer, use the focusElementOnClose prop in the Drawer component.

In the event you need to focus the alert, you can do so in one of three ways:

1. Automatically focus on mount.
2. Automatically focus on update.
3. Manually set focus.

Automatically focus on mount

Press the "Toggle alert" button below to mount/unmount the alert. Notice that each time the alert is mounted it will be focused. Here we use the focusOnMount boolean prop to automatically handle the focusing.

() => {
	const [showAlert, setShowAlert] = React.useState(false);

	return (
		<Stack gap={2}>
			<Button
				alignSelf="start"
				onClick={() => setShowAlert((prevShowAlert) => !prevShowAlert)}
			>
				Toggle alert
			</Button>

			{showAlert && (
				<PageAlert focusOnMount title="There is a problem" tone="error">
					<Text as="p">Please correct the following fields and try again</Text>
					<UnorderedList>
						<ListItem>
							<TextLink href="#">Full name must not be empty.</TextLink>
						</ListItem>
						<ListItem>
							<TextLink href="#">Email must not be empty.</TextLink>
						</ListItem>
					</UnorderedList>
				</PageAlert>
			)}
		</Stack>
	);
};

Automatically focus on update

Press the "Toggle alert" button below to mount/unmount the alert. Notice that each time the alert is mounted and subsequently updated it will be focused. Here we use the focusOnUpdate prop to automatically handle the focusing both on mount, and on updates to the alert's content.

Once the alert is displayed, try updating the content by pressing the "Update alert content" button. This will focus the alert.

() => {
	const availableErrors = [
		'Full name must not be empty.',
		'Email must not be empty.',
		'Phone number must not be empty.',
	];

	const [errors, setErrors] = React.useState([
		availableErrors[0], // When we have one error, we don't display the page alert (see do's and don'ts for more info)
	]);

	return (
		<Stack gap={2}>
			<Button
				alignSelf="start"
				onClick={() =>
					// Here we mock the updating of errors in our list
					setErrors((prevErrors) =>
						availableErrors
							.toReversed()
							.slice(availableErrors.length - prevErrors.length - 1)
							.reverse()
					)
				}
			>
				Update alert errors
			</Button>

			{errors.length > 1 && (
				<PageAlert
					focusOnUpdate={errors}
					title="There is a problem"
					tone="error"
				>
					<Text as="p">Please correct the following fields and try again</Text>
					<UnorderedList>
						{errors.map((text) => (
							<ListItem key={text}>
								<TextLink href="#">{text}</TextLink>
							</ListItem>
						))}
					</UnorderedList>
				</PageAlert>
			)}
		</Stack>
	);
};

Manually set focus

Press the "Focus the alert" button below to set focus on the alert. To achieve this, we set the tabIndex to -1. This will allow programmatic focusing and will render a focus ring to aid accessibility.

() => {
	const alertRef = React.useRef(null);

	return (
		<Stack gap={2}>
			<Button alignSelf="start" onClick={() => alertRef.current.focus()}>
				Focus the alert
			</Button>

			<PageAlert
				ref={alertRef}
				tabIndex={-1}
				title="Submission successful"
				tone="success"
			>
				<Text as="p">Your application has been successfully submitted.</Text>
			</PageAlert>
		</Stack>
	);
};

Customising the title

By default, PageAlert renders its title as an h2. However, should the need arise, you can change the title’s semantic tag to an h3, for example, by passing the PageAlertTitle component to the title prop. For information on maintaining proper heading levels, refer to Structuring headings and labels.

import { PageAlertTitle } from '@ag.ds-next/react/page-alert';

<PageAlert
	tone="success"
	title={<PageAlertTitle as="h3">Submission successful</PageAlertTitle>}
>
	<Text as="p">Your application has been successfully submitted.</Text>
</PageAlert>;

Related components

• Callout – Callouts are an excerpt of text used to draw attention to important or interesting information. They should not be confused with Page alerts.
• Global alert – Global alerts display prominent service or system wide messages at the top of the screen.
• Section alert – Section alerts are non-disruptive notifications that provide Success, Error and Warning messages about a state change in a section of a page.

Related patterns

• Accessible form validation and error recovery – Form validation is a critical aspect of creating usable and accessible applications. By providing effective error feedback and guidance, you can help users submit accurate information while minimising frustrations.
• 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.