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>

Title

By default, PageAlert renders PageAlertTitle as an h3. If you need to change the title’s semantic tag to an h2, for instance, you can use the PageAlertTitle component in the title prop to explicitly set it.

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

<PageAlert
	tone="success"
	title={<PageAlertTitle as="h2">Submission successful</PageAlertTitle>}
>
	<Text as="p">Your application has been successfully submitted.</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.

<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>

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.