Section alert

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

Section alerts appear inside of the main content area of the page and are used to alert users to a particular section of the screen. They should not be confused with Callouts.

<SectionAlert title="Your changes have been saved" tone="successHigh" />

Do

• use to notify users about a change in state in a section of a page
• use to communicate error, warning, success, informative or progress messages
• allow users to dismiss alerts that are not critical
• place above interactive components or at the top of page sections
• use constructive, no-blame language, avoid vague descriptions and always provide a solution
• keep it short - content should be understood at a glance
• use feedback that accurately communicates the state or progress
• apply the correct emphasis level to communicate the urgency or importance of the status tone.

Don’t

• use to communicate messages which relate to the entire page - use Page alert instead
• use to communicate messages which relate to the entire application - use Global alert instead
• change tone colours or apply new colours - the default colour set has semantic meaning that matches the ARIA label and meaningful image
• use to contain text in articles or other blocks of text content - use Callout instead
• close or hide the message automatically. Let the user dismiss the message instead
• repeat the title in the description
• use the description if the title is enough to convey the message
• include a close button for error messages.

Tones

Section alert can be used to communicate different types of messages. Choosing a tone for a Section alert allows the user to understand the importance and severity of the message at a glance.

The five supported tones are:

• Success
• Error
• Warning
• Information
• Progress

Success

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

<Stack gap={1}>
	<SectionAlert title="Your changes have been saved" tone="successHigh" />
</Stack>

Error

The error section alert (red) should be used when something destructive or critical has happened.

<Stack gap={1}>
	<SectionAlert
		title="There was an error saving your changes"
		tone="errorHigh"
	/>
</Stack>

Warning

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

<Stack gap={1}>
	<SectionAlert title="A warning message for this section" tone="warningHigh" />
</Stack>

Information

Use info section alerts (blue) to highlight information which is important for users.

<Stack gap={1}>
	<SectionAlert title="These records need more information" tone="infoHigh" />
</Stack>

Progress

Use in progress section alerts to highlight information which relates to status.

<Stack gap={1}>
	<SectionAlert title="Record is in progress" tone="inProgressLow" />
</Stack>

Status and emphasis

The tone prop combines both a status and emphasis, which sets the correct importance and severity of the Section alert by automatically applying appropriate colour, iconography and accessible descriptions.

There are nine unique tones with five levels of emphasis. All tones are available in Low emphasis but others are only available in Medium and High.

High emphasis

High emphasis Section alerts use filled icons and are available in four tone colours.

Use high emphasis section alerts for:

• important system messages
• notifications that require user action
• conveying urgent statuses in lists.

<Stack gap={1}>
	<SectionAlert title="Your changes have been saved" tone="successHigh" />
	<SectionAlert
		title="There was an error saving your changes"
		tone="errorHigh"
	/>
	<SectionAlert title="A warning message for this section" tone="warningHigh" />
	<SectionAlert
		title="An information message for this section"
		tone="infoHigh"
	/>
</Stack>

Medium emphasis

Medium emphasis Section alerts use stroked icons and are available in four tone colours.

Use medium emphasis section alerts to:

• convey non-urgent alerts.

<Stack gap={1}>
	<SectionAlert title="Your changes have been saved" tone="successMedium" />
	<SectionAlert
		title="There was an error saving your changes"
		tone="errorMedium"
	/>
	<SectionAlert
		title="A warning message for this section"
		tone="warningMedium"
	/>
	<SectionAlert
		title="An information message for this section"
		tone="infoMedium"
	/>
</Stack>

Low emphasis

Low emphasis Section alerts use stroked icons and are available in the default, neutral colour only.

Use low emphasis section alerts to:

• convey non-urgent alerts
• convey progress through a process.

<Stack gap={1}>
	<SectionAlert title="Success" tone="successLow" />
	<SectionAlert title="Error" tone="errorLow" />
	<SectionAlert title="Warning" tone="warningLow" />
	<SectionAlert title="Info" tone="infoLow" />
	<Divider />
	<SectionAlert title="Cannot start" tone="cannotStartLow" />
	<SectionAlert title="In progress" tone="inProgressLow" />
	<SectionAlert title="Paused" tone="pausedLow" />
	<SectionAlert title="Not started" tone="notStartedLow" />
	<SectionAlert title="Unknown" tone="unknownLow" />
</Stack>

Dismissable

Section alerts can be dismissed by a user if they have understood the message and no longer need to see it. Only use the close action when the alert does not impact the user’s available actions.

Avoid dismissing error messages which block the user from completing a task. Instead, provide a way for the user to fix the error, then dismiss the alert once the error has been resolved.

Use the onClose prop to make the alert dismissable.

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.

<SectionAlert
	onClose={console.log}
	title="Section alert title"
	tone="successHigh"
/>

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. The alert is focused each time it is mounted. The focusOnMount boolean prop automatically handles the focus management.

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

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

			{showAlert && (
				<SectionAlert
					focusOnMount
					title="Something went wrong"
					tone="errorHigh"
				>
					<Text as="p">There was an error submitting the application.</Text>
				</SectionAlert>
			)}
		</Stack>
	);
};

Automatically focus on update

Press the “Toggle alert” button below to mount/unmount the alert. The alert is focused each time it is mounted and its content is subsequently updated. The focusOnUpdate prop automatically handles the focus management.

Once the alert is displayed, update the content by pressing the “Update alert content” button. Focus will be automatically moved to the alert.

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

	const [errors, setErrors] = React.useState([]);

	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,
								availableErrors.length - prevErrors.length + 1
							)
							.reverse()
					)
				}
			>
				Update alert content
			</Button>

			{!!errors.length && (
				<SectionAlert
					focusOnUpdate={errors}
					title="Something went wrong"
					tone="errorHigh"
				>
					<UnorderedList>
						{errors.map((text) => (
							<ListItem key={text}>
								<Text as="p">{text}</Text>
							</ListItem>
						))}
					</UnorderedList>
				</SectionAlert>
			)}
		</Stack>
	);
};

Manually set focus

Press the “Focus the alert” button below to manually set focus on the alert. To achieve this, we must set tabIndex to -1 to allow programmatic focusing.

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

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

			<SectionAlert
				ref={alertRef}
				tabIndex={-1}
				title="Submission successful"
				tone="successHigh"
			>
				<Text as="p">Your application has been received.</Text>
			</SectionAlert>
		</Stack>
	);
};

Colour

AgDS foreground components respond to the background colour of their parent container. When placed on a dark palette background, the dark palette variant of the component is displayed. When placed on a light palette background, the light palette variant is displayed.

This logic ensures sufficient contrast between foreground and background elements is maintained to meet WCAG 2.1 AA 4.5:1 contrast ratio for text (WCAG 1.4.3) and 3:1 for graphic elements that convey information (WCAG 1.4.11).

<Fragment>
	<Box padding={1.5}>
		<SectionAlert title="Your changes have been saved" tone="successHigh" />
	</Box>

	<Box background="body" padding={1.5} palette="dark">
		<SectionAlert title="Your changes have been saved" tone="successHigh" />
	</Box>
</Fragment>

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.
• Page alert – Page alerts are colour-coded, non-disruptive notifications that provide Success, Error, Warning or Information messages at relevant times during the user journey. They should not be confused with Callouts.
• Status badge – Status badges are visual indicators used to highlight an item’s status for quick recognition.

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.