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