Some props/prop values deprecated in SWAN v3.3 Refer to the information on props/prop values provided further down this page. Find more information and migration documentation in the Deprecation roadmap.
Alert Box
Don't use Alert Box...
- For alert messages that apply to a specific section of the page. Use Status Message instead.
- For individual form field errors. Refer to Error guidelines for Forms.
The preview has been updated.
Skin
skin='standard'
is deprecated in SWAN v3.3
Use skin='info'
instead, which aligns with new semantic roles on SWAN components.
Info
Use skin="info"
for standard messages. This is the default skin.
The preview has been updated.
Positive
skin='positive'
is deprecated in SWAN v3.3
Use skin='success'
instead, which aligns with new semantic roles on SWAN components.
Use skin="positive"
for positive or success messages.
The preview has been updated.
Success
Use skin="success"
for positive or success messages.
The preview has been updated.
Warning
Use skin="warning"
for cautionary messages.
The preview has been updated.
Error
Use skin="error"
for error or critical messages.
The preview has been updated.
Legal Warning
Use skin="legal-warning"
when required for legal compliance messages such as those covered by California's Prop 65. There are specific legal requirements governing this messages icon, font size, and font color. They should not be dismissible.
The preview has been updated.
Dismissible
Dismissible alerts give users agency to remove messages after they have read them. For React, use AlertBoxDismissButton
to make Alert Box dismissible. For vanilla JS, use a button
with class="swan-alert-box-close-button"
to make Alert Box dismissible.
Localized text such as "Close alert" is required to describe the dismiss button to screen readers. For React, use accessibleText
. For vanilla JS, place the text inside the button.
The preview has been updated.
Controlled
For React, use dismissed
to take control of the dismissed state. Use onRequestDismiss
in order to be notified when the Alert Box wants to be dismissed.
The preview has been updated.
Narrow
width
is deprecated in SWAN v3.3
To maintain a high-quality user experience, we are no longer supporting this feature, and are not providing a direct replacement.
Use narrow
to apply a maximum width of 550px, or 344px on < md
breakpoints, to an Alert Box.
The preview has been updated.
Toast
Use toast for an Alert Box that pops upward over the page content, usually as an immediate response to user actions. Alert Box does not provide positioning or animation. Position them near the edge of the viewport.
The preview has been updated.
Implementation
Preserving user input
When an Alert Box occurs, it is important to preserve as much user input as possible. This allows the user to modify any incorrect information without having to re-enter it from scratch.
Accessible Text For Icon
When the severity of the alert is not obvious from text alone, a label for the icon must be provided using the accessibleTextForIcon
prop. This will announce the severity to assistive technology.
Alerts added page load
When dynamically adding an alert after initial page load, the content area where the alert will appear will need to already have role="status" aria-live="polite"
on it. These inform assistive technologies that they need to notify the user when any content inside that area changes, and thus the browser will announce the alert when it appears.
Positioning
- Place warnings or error alerts near the relevant issue to help users identify any specific actions they need to take.
- Avoid covering information that users need to move forward in their experience (e.g. CTAs, input fields, checkboxes).
- Page positioning is not included with Alert Box. Alerts that float above the page content, or those that have an animated pop-up toast style, must be setup during implementation.
Content
- Use clear, concise messages that inform and guide users.
- Users with vision issues may not be able to see the color of the Alert Box. The nature of the alert must be clear via text alone. It may be useful to add some
visually-hidden
text to the alert that won't show up on screens. For example, apositive
alert indicating that an operation has succeeded might have the visually hidden text "Success:" at the start of the message.
Alert Box with action
An Alert Box can become actionable by adding a Link or Link as a Button. Align the actions to the right side of the Alert Box.
Avoid using Button or Button as a Link.
The preview has been updated.
Props
<div />
as the root element. You can utilize the native attributes supported by <div />
tag. The ref
is directly assigned to the root element, allowing you to access and manipulate it as needed.prop | type | required | description | default |
---|---|---|---|---|
width | "standard" | "narrow" | null | false | ⚠️ Deprecated - This is deprecated without a replacement. | standard |
skin | "standard" | "info" | "success" | "warning" | "error" | "positive" | "legal-warning" | null | false | The visual style of the AlertBox
The 'standard' skin is deprecated; use 'info' instead
The 'positive' skin is deprecated; use 'success' instead | info |
toast | boolean | null | false | Whether or not the alert is a toast | false |
dismissed | boolean | null | false | Whether or not the alert is presently dismissed | null |
accessibleTextForIcon | string | null | false | Accessible text for the icon, that should be used for screen readers.
Typically it should indicate the type of alert eg. "info", "warning" | null |
onRequestDismiss | (() => void) | null | false | Callback fired when the user has requested that the alert be dismissed | null |
<button />
as the root element. You can utilize the native attributes supported by <button />
tag. The ref
is directly assigned to the root element, allowing you to access and manipulate it as needed.prop | type | required | description | default |
---|---|---|---|---|
visuallyHiddenLabel | ReactNodeLike | false | ⚠️ Deprecated - Use `accessibleText` instead
A localized label which describes the dismiss button to screen-reader users
Typically it is just a string like "Close" or "Dismiss alert" but can accept a ReactNode as well | null |
accessibleText | string | null | false | A localized label which describes the dismiss button to screen-reader users
Typically it is just a string like "Close" or "Dismiss alert" | null |
How does Alert Box meet your needs?