Skip to main content

Alert

Displays a callout for user attention. intent on Alert.Root is required: it sets the color and the default icon.

When to use

  • Show a persistent message in the page, such as a warning, an error, or a success note, beside the content it describes.
  • Show a full-width notice at the top of a region with a banner.
  • Prefer Toast when the message is brief and goes away on its own.
  • Prefer AlertDialog when the user must respond before they continue.
  • Prefer AlertCenter when several account-level alerts share one bar at the top of the app.
  • Prefer Empty when a region has no data, no results, or no access to show.

Composition

Compose the parts of an Alert together to build your own:

Alert.Root├── Alert.Icon├── Alert.Content    ├── Alert.Title    ├── Alert.Description    ├── Alert.ExpandButton    └── Alert.DismissIconButton

Polymorphism

Alert.Title and Alert.Description support asChild when the alert's surrounding document structure needs a different semantic element.

Intents

intent sets the color and the default icon of the alert.

Custom icon

Pass the svg prop to Alert.Icon to replace the default icon of the intent.

Layouts

Mix and match what you put inside the Alert component to create different Alert layouts.

Banners

For banner-like alerts, use the appearance="banner" prop. This automatically removes the top, left, and right border, leaving only the bottom border.

Dismissal

Alert.DismissIconButton removes nothing on its own. Your state does: stop rendering the alert in its onClick handler. When that unmount happens while the dismiss button holds focus, focus moves to the nearest tabbable element outside the alert: the next one in document order, or the previous one when nothing follows. Without that move, focus falls to <body> and the next Tab restarts at the top of the page. A screen reader user also gets no confirmation that the alert left. If your handler or a layout effect places focus first, the alert keeps that choice.

In the demo below, Tab to the dismiss button and press Enter. Focus lands on the button that follows the alert.

Expand button

Use Alert.ExpandButton for a compact control that reveals related alerts. It sits at the trailing edge, to the left of the dismiss button when both are present, and reserves space for the count and caret, so alert copy remains contained on narrow viewports. It shows +N on mobile and +N more from the md (tablet) breakpoint.

Dismiss and expand

Alert.DismissIconButton and Alert.ExpandButton compose safely in the same alert. Both stay absolutely positioned at the trailing edge. When both are present, the dismiss button stays rightmost, the expander moves to its left, and Alert.Content reserves room for the pair. Put Alert.ExpandButton before Alert.DismissIconButton in your markup so the Tab order matches the visual order. This also handles an alert that first renders dismissable and later gains an expander as more alerts arrive.

Trailing control colors

Alert.DismissIconButton and Alert.ExpandButton share the following CSS custom properties from Alert.Root. Each intent supplies the listed defaults; set them once on the root to theme both controls together.

VariableDefaultUsed for
--alert-control-colorvar(--color-<intent>-700)Control text and icon color.
--alert-control-hover-colorvar(--color-<intent>-800)Control text and icon color on hover.
--alert-control-hover-bgcolor-mix(in oklab, var(--color-<intent>-500) 10%, transparent)Control background on hover.

Custom dismiss icon

Use the icon prop on Alert.DismissIconButton to render a custom icon in place of the default X.

Announcing a dynamic alert

Alert.Root renders a plain <div> with no ARIA role. A static alert that is on the page at load does not need one. When your code inserts an alert after an action, such as "Invalid email or password." after a submit, pass role="alert" so a screen reader announces it.

The role alone is not reliable. Assistive tech can miss a live region that mounts already populated. For an error the user must act on, also move focus to the alert: set tabIndex={-1} and focus it on mount. Focus also puts a sighted user's attention on what went wrong. For a less urgent message, pass role="status" on a region that is already mounted, and write the message into it.

The demo below rejects every sign-in, so the alert mounts after the action. The key remounts the alert on a repeated attempt, so it announces again.

API Reference

Alert.Root

Displays a callout for user attention. Root container for all Alert sub-components. It has no ARIA role of its own. When your code inserts the alert after an action, pass role="alert" and move focus to it; see Announcing a dynamic alert.

All props from div, plus:

PropTypeDefaultDescription
appearance?"default" | "banner""default"Controls the visual style. "default" keeps the standard rounded corners and borders. "banner" creates a banner-style alert with no rounded corners, sticky positioning, and no top, left, or right borders.
intent"danger" | "important" | "info" | "success" | "warning"The tone of the Alert. Sets the color, styling, and default icon to communicate the status it reports.

Trailing control CSS variables

Alert.Root defines --alert-control-color, --alert-control-hover-color, and --alert-control-hover-bg from its intent. Both Alert.DismissIconButton and Alert.ExpandButton inherit them. Override the variables on the root to theme both trailing controls together.

CSS VariableDefaultDescription
--alert-control-colorvar(--color-<intent>-700)Control text and icon color.
--alert-control-hover-colorvar(--color-<intent>-800)Control text and icon color on hover.
--alert-control-hover-bgcolor-mix(in oklab, var(--color-<intent>-500) 10%, transparent)Control background on hover.

Alert.Content

The container for the content slot of an Alert. Place Alert.Title, Alert.Description, Alert.DismissIconButton, and Alert.ExpandButton as direct children.

All props from div.

Alert.ExpandButton

Positions a compact expand/collapse control at the trailing edge of an Alert. Its count is displayed beside a caret that rotates when expanded is true. It shares the root-level trailing-control CSS variables with Alert.DismissIconButton.

All props from Button, plus:

PropTypeDefaultDescription
countnumberThe number of hidden related alerts, displayed with a leading +.
expandedbooleanWhether the related alerts are visible; rotates the caret when true.

Alert.Description

The optional description of an Alert. Renders as a div by default, but can be changed to any other element using the asChild prop.

All props from div, plus:

PropTypeDefaultDescription
asChild?booleanfalseUse the asChild prop to compose the AlertDescription styling onto alternative element types or your own React components.

Alert.Icon

An optional icon that visually represents the intent of the Alert. Pass the svg prop to replace the default icon.

All props from svg, plus:

PropTypeDefaultDescription
svg?ReactNodeAn optional icon that renders in place of the default icon for the Alert intent.

Alert.Title

The title of an Alert. Renders as an h5 element by default; use asChild to render something else.

All props from h5, plus:

PropTypeDefaultDescription
asChild?booleanfalseUse the asChild prop to compose the AlertTitle styling onto alternative element types or your own React components.

Alert.DismissIconButton

A dismiss icon button. Your onClick handler removes the alert. When that unmount happens while the button holds focus, focus moves to the nearest tabbable element outside the alert; see Dismissal. It shares the root-level trailing-control CSS variables with Alert.ExpandButton.

All props from IconButton, with the following overridden defaults:

PropTypeDefaultDescription
appearance?"filled" | "ghost" | "outlined""ghost"The visual style of the button.
icon?ReactNode<XIcon />An optional icon to render inside the dismiss button. Defaults to an X icon.
label?string"Dismiss Alert"The accessible label for the button, announced to screen readers.
size?"xs" | "sm" | "md""sm"The size of the button.
type?"button" | "submit" | "reset""button"The default behavior of the button.