Skip to content
flyingsalmon

Alert

An in-flow message that reports the result of an action where the traveller is already looking, and stays until they have seen it.

Trip saved
Six days in Lisbon, ready to share.

Installation

npx shadcn@latest add @flyingsalmon/alert

Usage

import {
  Alert,
  AlertDescription,
  AlertTitle,
  AlertVariant,
} from '@/components/ui/alert'

export function AlertUsage() {
  return (
    <Alert variant={AlertVariant.Success}>
      <AlertTitle>Trip saved</AlertTitle>
      <AlertDescription>Six days in Lisbon, ready to share.</AlertDescription>
    </Alert>
  )
}

Examples

Variants

Info is the default, then success, warning, and error. The card and its border stay plain, and the icon alone carries the variant, so an alert reads as a message on the page and never as a coloured block.

Saved as a draft
Trip saved
Two seats left at this price

Sizes

Small tightens the padding and the icon for an alert inside a dense surface. The text size does not change: a message does not shrink its type.

Trip saved
Trip saved

Title and description

The title is optional; a short message works on its own. When both are present the description steps back to the muted colour, so the title is read first.

Flight prices changed
Lisbon to Porto is now 20 euros more for Brian Nguyen and two travellers.

Custom icon

Pass icon to replace the variant icon, or null to drop it. The alert sizes and colours whatever node you pass.

Everyone has said yes
Everyone has said yes

Dismissible

Pass onClose and the alert shows a Dismiss button. The alert never hides itself: it calls onClose and your app decides what happens, so the app can retry or keep the message until the traveller has seen it.

Invite sent
Brian Nguyen invited two travellers to Lisbon.

With actions

Put the buttons in the children, under the description. Two at most, one outline and one ghost, both small. A third action means the message belongs somewhere bigger than an alert.

Open and close

open grows the alert in and shrinks it out. The alert carries its own exit, so you toggle open and write no motion code.

In a form's result slot

Submit the form. The button shows its own busyness, then the failure appears below the actions row, where the traveller is already looking, with their input kept.

Guidelines

When to use

  • To report the result of a form submit, in the form’s result slot below the actions row.
  • To show a warning or notice that belongs to a region of the page and should sit in the flow beside it.

When not to use

  • Use Notice for a result with no visible home, such as the outcome of a dialog form that has already closed. A notice stays on screen and links back to its subject.
  • Use Error state when a region failed to load. The region itself says so, with a retry.
  • Use Fields for the error on a single field. The field shows its own error beside its input.

Do and don’t

  • Do
    Place the alert where the traveller is already looking, and keep it until they have seen it.A message that appears elsewhere or disappears on a timer is missed, and a missed failure looks like a success.
  • Do
    Pick the variant by what the traveller must do: error for a failure, warning for something to check, success and info for the rest.The colour and icon tell the traveller whether to stop, check, or carry on before they read a word.
  • Do
    Write the title as what happened, in a sentence, and the description as what to do next or what was kept. Put the way forward inside the alert as a link or a button.The traveller reads the fact, then finds the next step without leaving the message.
  • Do
    Show a standing condition, such as trips saved only in this browser, as a warning at the top of the page with its action inside.It stays true until the traveller acts, so it sits where every visit starts.
  • Don’t
    Let an alert vanish on a timer. It goes when the traveller closes it or the state it reports ends.A message that removes itself cannot be read at the traveller’s pace.
  • Don’t
    Stack several alerts for one result.Several messages for one result make the traveller work out which one matters. Write one alert that says it. A separate condition, such as each day that clashes, gets its own.

Accessibility

KeyDescription
TabMoves focus to the Dismiss button when onClose is passed, after any action buttons in the body. Without onClose the alert has no tab stop.
EnterSpaceOn the Dismiss button, calls onClose.

An error alert has role="alert", so a screen reader interrupts with it. The other three variants have role="status" and wait their turn. Pass role to override the mapping. The icon is hidden from assistive technology, so the message is announced once.

The alert does no focus management. When you remove an alert whose Dismiss button holds focus, send focus back to the control that produced it.

API

Alert

Also takes every <div> attribute. AlertTitle and AlertDescription take only their element’s props.

PropTypeDefaultDescription
variantAlertVariantAlertVariant.InfoInfo, Success, Warning, or Error. Error interrupts a screen reader; the others wait their turn.
sizeAlertSizeAlertSize.DefaultDefault or Small. The text size is the same in both.
iconReactNode–Replaces the variant icon. Pass null to show no icon.
onClose() => void–Shows a Dismiss button that calls it. The alert does not hide itself: your app owns its lifecycle and sets open or removes it.
openbooleantrueShows or hides the alert, animating the change.
animateOpenbooleantrueSet false to skip the height animation.
rolestring–Overrides the role the variant sets: alert for error, status for the rest.

  • Notice

    The persistent shell surface for a result with no visible home.
  • Error state

    The failed state of a region that did not load.
  • Form

    Defines the result slot an alert sits in.
  • Principles

    The feedback rule that ranks where a result belongs.