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="success" />

Do

• use to notify users about a change in state in a section of a page
• use to communicate error, warning or success 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 the appropriate status and tone of success, error or warning.

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
• use to contain text in articles or other blocks of text content - use Callout instead
• 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 three supported tones are success, error and warning.

Success

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

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

Error

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

<SectionAlert title="There was an error saving your changes" tone="error" />

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.

<SectionAlert title="A warning message for this section" tone="warning" />

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
	title="Section alert title"
	tone="success"
	onClose={console.log}
/>

Composition

Section alerts are composed of an icon, title, description, action and close action.

The icon and title are mandatory and achieve a compact alert, but we encourage the use of description when additional information might be helpful to the user.

<Stack gap={1}>
	<SectionAlert
		title="Section alert title"
		tone="success"
		onClose={console.log}
	/>

	<SectionAlert title="Section alert title" tone="success">
		<Text as="p">Description</Text>
	</SectionAlert>

	<SectionAlert title="Section alert title" tone="warning">
		<Stack gap={0.5} alignItems="flex-start">
			<Text as="p">Description</Text>
			<ButtonGroup>
				<Button variant="text">Action 1</Button>
				<Button variant="text">Action 2</Button>
			</ButtonGroup>
		</Stack>
	</SectionAlert>
</Stack>

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 && (
				<SectionAlert focusOnMount title="Something went wrong" tone="error">
					<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. 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.',
	];

	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="error"
				>
					<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 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>

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

Related components

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

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.