Alert Box

A prominent method of messaging users about important information.

scriptKeys: alertBoxstyleKeys: alertBox

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.

UsageGuidelinesAPI

Use Alert Box...

For alert messages that apply to an entire page, or to a section of a page.
For alert messages that float over page content. Refer to Toasts.
For destructible and interruptible tasks. Refer to Warning and Error skins.

Don't use Alert Box...

For individual form field errors. Refer to Error guidelines for Forms.

ReactVanilla

<AlertBox>Alert Box</AlertBox>

<AlertBox>Alert Box</AlertBox>

<div role="alert" class="swan-alert-box">Alert Box</div>

<div role="alert" class="swan-alert-box">Alert Box</div>

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.

ReactVanilla

<AlertBox skin="info">
  Info
  <AlertBoxDismissButton accessibleText="Dismiss alert" />
</AlertBox>

<AlertBox skin="info">
  Info
  <AlertBoxDismissButton accessibleText="Dismiss alert" />
</AlertBox>

<div role="alert" class="swan-alert-box-info">
  Info
  <button class="swan-alert-box-close-button">Dismiss alert</button>
</div>

<div role="alert" class="swan-alert-box-info">
  Info
  <button class="swan-alert-box-close-button">Dismiss alert</button>
</div>

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.

ReactVanilla

<AlertBox skin="positive">
  Positive
  <AlertBoxDismissButton accessibleText="Dismiss alert" />
</AlertBox>

<AlertBox skin="positive">
  Positive
  <AlertBoxDismissButton accessibleText="Dismiss alert" />
</AlertBox>

<div role="alert" class="swan-alert-box swan-alert-box-skin-positive">
  Positive
  <button class="swan-alert-box-close-button">Dismiss alert</button>
</div>

<div role="alert" class="swan-alert-box swan-alert-box-skin-positive">
  Positive
  <button class="swan-alert-box-close-button">Dismiss alert</button>
</div>

Success

Use skin="success" for positive or success messages.

ReactVanilla

<AlertBox skin="success">
  Success
  <AlertBoxDismissButton accessibleText="Dismiss alert" />
</AlertBox>

<AlertBox skin="success">
  Success
  <AlertBoxDismissButton accessibleText="Dismiss alert" />
</AlertBox>

<div role="alert" class="swan-alert-box swan-alert-box-skin-success">
  Success
  <button class="swan-alert-box-close-button">Dismiss alert</button>
</div>

<div role="alert" class="swan-alert-box swan-alert-box-skin-success">
  Success
  <button class="swan-alert-box-close-button">Dismiss alert</button>
</div>

Warning

Use skin="warning" for cautionary messages.

ReactVanilla

<AlertBox skin="warning">
  Warning
  <AlertBoxDismissButton accessibleText="Dismiss alert" />
</AlertBox>

<AlertBox skin="warning">
  Warning
  <AlertBoxDismissButton accessibleText="Dismiss alert" />
</AlertBox>

<div role="alert" class="swan-alert-box swan-alert-box-skin-warning">
  Warning
  <button class="swan-alert-box-close-button">Dismiss alert</button>
</div>

<div role="alert" class="swan-alert-box swan-alert-box-skin-warning">
  Warning
  <button class="swan-alert-box-close-button">Dismiss alert</button>
</div>

Error

Use skin="error" for error or critical messages.

ReactVanilla

<AlertBox skin="error">
  Error
  <AlertBoxDismissButton accessibleText="Dismiss alert" />
</AlertBox>

<AlertBox skin="error">
  Error
  <AlertBoxDismissButton accessibleText="Dismiss alert" />
</AlertBox>

<div role="alert" class="swan-alert-box swan-alert-box-skin-error">
  Error
  <button class="swan-alert-box-close-button">Dismiss alert</button>
</div>

<div role="alert" class="swan-alert-box swan-alert-box-skin-error">
  Error
  <button class="swan-alert-box-close-button">Dismiss alert</button>
</div>

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.

ReactVanilla

<AlertBox skin="legal-warning">
  <strong>WARNING</strong>: This product can expose you to Diisononyl Phthalate
  (DINP), which is known to the State of California to cause cancer. For more
  information go to{' '}
  <a href="http://www.P65Warnings.ca.gov">www.P65Warnings.ca.gov</a>.
</AlertBox>

<AlertBox skin="legal-warning">
  <strong>WARNING</strong>: This product can expose you to Diisononyl Phthalate
  (DINP), which is known to the State of California to cause cancer. For more
  information go to{' '}
  <a href="http://www.P65Warnings.ca.gov">www.P65Warnings.ca.gov</a>.
</AlertBox>

<div role="alert" class="swan-alert-box swan-alert-box-skin-legal-warning">
  <img
    src="https://swan.prod.merch.vpsvc.com/v0.0.2-main.13-hashed/images/legal-warning.14e030436e9ab3e5a708ec3fb9d655a1.png"
    alt="warning"
  /><strong>WARNING</strong>: This product can expose you to Diisononyl
  Phthalate (DINP), which is known to the State of California to cause cancer.
  For more information go to
  <a href="http://www.P65Warnings.ca.gov">www.P65Warnings.ca.gov</a>.
</div>

<div role="alert" class="swan-alert-box swan-alert-box-skin-legal-warning">
  <img
    src="https://swan.prod.merch.vpsvc.com/v0.0.2-main.13-hashed/images/legal-warning.14e030436e9ab3e5a708ec3fb9d655a1.png"
    alt="warning"
  /><strong>WARNING</strong>: This product can expose you to Diisononyl
  Phthalate (DINP), which is known to the State of California to cause cancer.
  For more information go to
  <a href="http://www.P65Warnings.ca.gov">www.P65Warnings.ca.gov</a>.
</div>

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.

ReactVanilla

<AlertBox>
  Alert
  <AlertBoxDismissButton accessibleText="Dismiss alert" />
</AlertBox>

<AlertBox>
  Alert
  <AlertBoxDismissButton accessibleText="Dismiss alert" />
</AlertBox>

<div role="alert" class="swan-alert-box">
  Alert
  <button class="swan-alert-box-close-button">Dismiss alert</button>
</div>

<div role="alert" class="swan-alert-box">
  Alert
  <button class="swan-alert-box-close-button">Dismiss alert</button>
</div>

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.

ReactVanilla

() => {
  const [dismissed, setDismissed] = React.useState(false)
  return (
    <AlertBox
      dismissed={dismissed}
      onRequestDismiss={() => {
        setDismissed(true)
        // for demo purposes, we'll un-dismiss the alert after a few seconds
        setTimeout(() => {
          setDismissed(false)
        }, 2000)
      }}
    >
      Controlled
      <AlertBoxDismissButton accessibleText="Dismiss alert" />
    </AlertBox>
  )
}

() => {
  const [dismissed, setDismissed] = React.useState(false)
  return (
    <AlertBox
      dismissed={dismissed}
      onRequestDismiss={() => {
        setDismissed(true)
        // for demo purposes, we'll un-dismiss the alert after a few seconds
        setTimeout(() => {
          setDismissed(false)
        }, 2000)
      }}
    >
      Controlled
      <AlertBoxDismissButton accessibleText="Dismiss alert" />
    </AlertBox>
  )
}

<div role="alert" class="swan-alert-box">
  Controlled
  <button class="swan-alert-box-close-button">Dismiss alert</button>
</div>

<div role="alert" class="swan-alert-box">
  Controlled
  <button class="swan-alert-box-close-button">Dismiss alert</button>
</div>

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.

ReactVanilla

<AlertBox width="narrow">
  Narrow
  <AlertBoxDismissButton accessibleText="Dismiss alert" />
</AlertBox>

<AlertBox width="narrow">
  Narrow
  <AlertBoxDismissButton accessibleText="Dismiss alert" />
</AlertBox>

<div role="alert" class="swan-alert-box swan-alert-box-narrow">
  Narrow
  <button class="swan-alert-box-close-button">Dismiss alert</button>
</div>

<div role="alert" class="swan-alert-box swan-alert-box-narrow">
  Narrow
  <button class="swan-alert-box-close-button">Dismiss alert</button>
</div>

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.

ReactVanilla

<AlertBox toast>Toast</AlertBox>

<AlertBox toast>Toast</AlertBox>

<div role="alert" class="swan-alert-box swan-alert-box-toast">Toast</div>

<div role="alert" class="swan-alert-box swan-alert-box-toast">Toast</div>

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.

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, a positive alert indicating that an operation has succeeded might have the visually hidden text "Success:" at the start of the message.

Props

AlertBox

This component is implemented using the <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.

See core props for additional props that can be applied to this component.

prop	type	required	description	default
width	`"standard" \| "narrow" \| null`	false	⚠️ Deprecated - This is deprecated without a replacement. The width of the AlertBox	"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	null
dismissed	`boolean \| null`	false	Whether or not the alert is presently dismissed	null
onRequestDismiss	`(() => void) \| null`	false	Callback fired when the user has requested that the alert be dismissed	null

AlertBoxDismissButton

This component is implemented using the <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.

See core props for additional props that can be applied to this component.

prop	type	required	description	default
visuallyHiddenLabel	`ReactNodeLike`	false	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	Serves same purpose as `visuallyHiddenLabel` but accepts only string. In the long run, we prefer this over the former.	null

Was this page useful?

Published: Jan 7, 2022Last updated: Oct 17, 2024