Alert

import { Alert, AlertDescription, AlertTitle } from "@hel/ui/alert"

export function AlertDemo() {

When to use it#

Use an alert for a message that belongs to the page and stays there until it stops being true: a notice about the data, the result of saving, a warning before a step, or the errors of a form.

It is not a notification. For a message that appears for a moment and goes away on its own, use a Toast. For a question that blocks the page until it is answered, use an Alert Dialog.

Import#

Copyimport {
  Alert,
  AlertTitle,
  AlertDescription,
  AlertActions,
} from "@hel/ui/alert"

Anatomy#

Alert is the box. Put an AlertTitle for the headline, an AlertDescription for the details, and AlertActions for buttons. All three are optional, and a one-line alert can hold plain text.

Copy<Alert tone="warning">
  <AlertTitle>The period closes in 2 days</AlertTitle>
  <AlertDescription>Post the remaining journal entries before 31 October.</AlertDescription>
</Alert>

Tones#

tone says what the message is about, and sets the icon and the colors. neutral is a plain note, info is the default, and success, warning and error use the theme's status colors.

The tone also decides how screen readers announce the alert. Errors and warnings interrupt, and the other tones wait for a pause. The tone is read out before the text, so it does not rely on color and icon alone.

import { Alert, AlertDescription, AlertTitle } from "@hel/ui/alert"
import type { AlertTone } from "@hel/ui/alert"
import { Stack } from "@hel/ui/stack"

Looks#

variant changes the shape of the alert, not its meaning.

• callout is a tinted box, for notices inside a page or a form. It is the default.
• outline keeps the page's surface and only tints the border, which works on busy or colored backgrounds.
• banner runs the full width with a line under it, for a message across the top of a page or a panel.
• inline has no box. The icon and the text take the tone's color, for a line under a form or a table.

size is md or sm, and icon changes the icon, or removes it with false.

import { Alert, AlertDescription, AlertTitle } from "@hel/ui/alert"
import { Stack } from "@hel/ui/stack"

Examples#

Dismissible#

Set dismissible to add a close button. Closing hides the alert and calls onOpenChange. Leave open out and the alert looks after itself, or control it with open, as here, to bring it back.

import * as React from "react"

import { Alert, AlertDescription, AlertTitle } from "@hel/ui/alert"

Buttons#

A longer alert can hold buttons. Put them in AlertActions, below the text. For a short, one-line alert, use the action prop instead. It puts one link or button at the end of the row.

This example is a load error with a retry that gives feedback, and a success line when it works.

import * as React from "react"
import { CloudOff, RefreshCw } from "lucide-react"

Announcing it#

Screen readers hear an alert when it appears, which is right for a result that shows up after an action. For a note that is on the page from the start, such as a banner that is always there, set live="off" so it is not read out of turn. live can also be polite or assertive to override the tone's default.

Props#