Alert Box

A prominent method of messaging users about important information.

scriptKeys: alertBoxstyleKeys: alertBox

UsageGuidelinesAPI

Use Alert Box...

For alert messages that apply to an entire 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 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.

accessibleText and accessibleTextForIcon are deprecated in SWAN 3.24. These prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system and remove these prop.

ReactVanilla

<AlertBox accessibleTextForIcon="Info">Alert Box</AlertBox>

<AlertBox accessibleTextForIcon="Info">Alert Box</AlertBox>

<div role="alert" class="swan-alert-box">
  <span
    role="img"
    aria-label="Info"
    class="swan-alert-box-icon swan-alert-box-icon-info"
  ></span
  >Alert Box
</div>

<div role="alert" class="swan-alert-box">
  <span
    role="img"
    aria-label="Info"
    class="swan-alert-box-icon swan-alert-box-icon-info"
  ></span
  >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 />
</AlertBox>

<AlertBox skin="info">
  Info
  <AlertBoxDismissButton />
</AlertBox>

<div role="alert" class="swan-alert-box">
  <span
    role="img"
    aria-label="Info"
    class="swan-alert-box-icon swan-alert-box-icon-info"
  ></span
  >Info<button class="swan-alert-box-close-button">
    <span class="swan-visually-hidden">Dismiss alert</span>
  </button>
</div>

<div role="alert" class="swan-alert-box">
  <span
    role="img"
    aria-label="Info"
    class="swan-alert-box-icon swan-alert-box-icon-info"
  ></span
  >Info<button class="swan-alert-box-close-button">
    <span class="swan-visually-hidden">Dismiss alert</span>
  </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 />
</AlertBox>

<AlertBox skin="positive">
  Positive
  <AlertBoxDismissButton />
</AlertBox>

<div role="alert" class="swan-alert-box swan-alert-box-skin-positive">
  <span
    role="img"
    aria-label="Positive"
    class="swan-alert-box-icon swan-alert-box-icon-positive"
  ></span
  >Positive<button class="swan-alert-box-close-button">
    <span class="swan-visually-hidden">Dismiss alert</span>
  </button>
</div>

<div role="alert" class="swan-alert-box swan-alert-box-skin-positive">
  <span
    role="img"
    aria-label="Positive"
    class="swan-alert-box-icon swan-alert-box-icon-positive"
  ></span
  >Positive<button class="swan-alert-box-close-button">
    <span class="swan-visually-hidden">Dismiss alert</span>
  </button>
</div>

Success

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

ReactVanilla

<AlertBox skin="success">
  Success
  <AlertBoxDismissButton />
</AlertBox>

<AlertBox skin="success">
  Success
  <AlertBoxDismissButton />
</AlertBox>

<div role="alert" class="swan-alert-box swan-alert-box-skin-success">
  <span
    role="img"
    aria-label="Success"
    class="swan-alert-box-icon swan-alert-box-icon-success"
  ></span
  >Success<button class="swan-alert-box-close-button">
    <span class="swan-visually-hidden">Dismiss alert</span>
  </button>
</div>

<div role="alert" class="swan-alert-box swan-alert-box-skin-success">
  <span
    role="img"
    aria-label="Success"
    class="swan-alert-box-icon swan-alert-box-icon-success"
  ></span
  >Success<button class="swan-alert-box-close-button">
    <span class="swan-visually-hidden">Dismiss alert</span>
  </button>
</div>

Warning

Use skin="warning" for cautionary messages.

ReactVanilla

<AlertBox skin="warning">
  Warning
  <AlertBoxDismissButton />
</AlertBox>

<AlertBox skin="warning">
  Warning
  <AlertBoxDismissButton />
</AlertBox>

<div role="alert" class="swan-alert-box swan-alert-box-skin-warning">
  <span
    role="img"
    aria-label="Warning"
    class="swan-alert-box-icon swan-alert-box-icon-warning"
  ></span
  >Warning<button class="swan-alert-box-close-button">
    <span class="swan-visually-hidden">Dismiss alert</span>
  </button>
</div>

<div role="alert" class="swan-alert-box swan-alert-box-skin-warning">
  <span
    role="img"
    aria-label="Warning"
    class="swan-alert-box-icon swan-alert-box-icon-warning"
  ></span
  >Warning<button class="swan-alert-box-close-button">
    <span class="swan-visually-hidden">Dismiss alert</span>
  </button>
</div>

Error

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

ReactVanilla

<AlertBox skin="error">
  Error
  <AlertBoxDismissButton />
</AlertBox>

<AlertBox skin="error">
  Error
  <AlertBoxDismissButton />
</AlertBox>

<div role="alert" class="swan-alert-box swan-alert-box-skin-error">
  <span
    role="img"
    aria-label="Error"
    class="swan-alert-box-icon swan-alert-box-icon-error"
  ></span
  >Error<button class="swan-alert-box-close-button">
    <span class="swan-visually-hidden">Dismiss alert</span>
  </button>
</div>

<div role="alert" class="swan-alert-box swan-alert-box-skin-error">
  <span
    role="img"
    aria-label="Error"
    class="swan-alert-box-icon swan-alert-box-icon-error"
  ></span
  >Error<button class="swan-alert-box-close-button">
    <span class="swan-visually-hidden">Dismiss alert</span>
  </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/v3/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/v3/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.

ReactVanilla

<AlertBox>
  Alert
  <AlertBoxDismissButton />
</AlertBox>

<AlertBox>
  Alert
  <AlertBoxDismissButton />
</AlertBox>

<div accessibletexforicon="Info" role="alert" class="swan-alert-box">
  <span class="swan-alert-box-icon swan-alert-box-icon-info"></span>Alert<button
    class="swan-alert-box-close-button"
  >
    <span class="swan-visually-hidden">Dismiss alert</span>
  </button>
</div>

<div accessibletexforicon="Info" role="alert" class="swan-alert-box">
  <span class="swan-alert-box-icon swan-alert-box-icon-info"></span>Alert<button
    class="swan-alert-box-close-button"
  >
    <span class="swan-visually-hidden">Dismiss alert</span>
  </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.

() => {
  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 />
    </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 />
    </AlertBox>
  )
}

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 />
</AlertBox>

<AlertBox width="narrow">
  Narrow
  <AlertBoxDismissButton />
</AlertBox>

<div role="alert" class="swan-alert-box swan-alert-box-narrow">
  <span
    role="img"
    aria-label="Info"
    class="swan-alert-box-icon swan-alert-box-icon-info"
  ></span
  >Narrow<button class="swan-alert-box-close-button">
    <span class="swan-visually-hidden">Dismiss alert</span>
  </button>
</div>

<div role="alert" class="swan-alert-box swan-alert-box-narrow">
  <span
    role="img"
    aria-label="Info"
    class="swan-alert-box-icon swan-alert-box-icon-info"
  ></span
  >Narrow<button class="swan-alert-box-close-button">
    <span class="swan-visually-hidden">Dismiss alert</span>
  </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 accessibleTextForIcon="Info">
  Toast
</AlertBox>

<AlertBox toast accessibleTextForIcon="Info">
  Toast
</AlertBox>

<div
  role="alert"
  class="swan-vanilla-ignore swan-alert-box swan-alert-box-toast"
>
  <span
    role="img"
    aria-label="Info"
    class="swan-alert-box-icon swan-alert-box-icon-info"
  ></span
  >Toast
</div>

<div
  role="alert"
  class="swan-vanilla-ignore swan-alert-box swan-alert-box-toast"
>
  <span
    role="img"
    aria-label="Info"
    class="swan-alert-box-icon swan-alert-box-icon-info"
  ></span
  >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.

Accessibility

If not using SWAN's i18n system, AlertBox requires the following accessible props for a11y compliance:

An accessible label for the icon must be provided using the accessibleTextForIcon prop. This will announce the severity to assistive technology. Ensure this is localized as it will be read out to the user.
If using AlertBoxDismissButton you must provide the accessibleText prop used to describe the action to screen readers e.g. "Dismiss alert". Ensure this is localized as it will be read out to the user.

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.
Place Alert Box 16px from the viewport's top or bottom edge, either centered within the content area or aligned to the right side of the screen. On mobile, place Alert Box at the bottom center of the screen.

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.
Text content must be left-aligned. Do not use centre-aligned or right-aligned paragraphs of text.

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.

<AlertBox skin="info">
  <FlexBox justifyContent="space-between">
    Info
    <Link
      render={({ children, ...rest }) => (
        <Button skin="link" {...rest}>
          {children}
        </Button>
      )}
    >
      I am a button
    </Link>
  </FlexBox>
  <AlertBoxDismissButton />
</AlertBox>

<AlertBox skin="info">
  <FlexBox justifyContent="space-between">
    Info
    <Link
      render={({ children, ...rest }) => (
        <Button skin="link" {...rest}>
          {children}
        </Button>
      )}
    >
      I am a button
    </Link>
  </FlexBox>
  <AlertBoxDismissButton />
</AlertBox>

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
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
width	`"standard" \| "narrow" \| null`	false	⚠️ Deprecated - This is deprecated without a replacement.	standard
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	⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support. 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

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	`ReactNode`	false	⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support. 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	⚠️ Deprecated - This prop will be removed in favor of SWAN's i18n system. Please opt in to the i18n system for continued support. A localized label which describes the dismiss button to screen-reader users Typically it is just a string like "Close" or "Dismiss alert"	null