Alert
An inline banner that calls out a status or important message.
@garn/ui/alertOn this page
Default
Default alert with icon, title, and description.
Appearance
Color intent. info/success/warning/danger are subtle status banners built on the Tier-2 status tokens.
Neutral
A neutral, non-status notice — context or general information with no intent color.
Status
Intent-carrying banners — info for context, success to confirm, warning to caution, danger for genuine errors.
Installation
garn is copy-in — the garn CLI writes this component's source into your project, so you own and can edit it. It resolves any base files and installs the npm dependencies below for you.
npx garn-ui add alert- Registry
alert- Deps
class-variance-authority- Registry deps
utils
Import
import { Alert, AlertTitle, AlertDescription } from "@garn/ui/alert";Anatomy
The parts this component is built from — compose them to assemble it.
AlertRequired[data-slot="alert"]The banner (role=alert); carries the tone. An optional leading <svg> is absolutely positioned.
AlertTitle[data-slot="alert-title"]The short headline (an <h5>).
AlertDescription[data-slot="alert-description"]The supporting body text.
Props
The component's public props and their types.
tone- Description
- No description.
- Type
"danger" | "info" | "neutral" | "success" | "warning"- Default
neutral
Plus 280 inherited native <div> attributes.
Styling
Target these data-slots and states, and remap these tokens, to restyle without forking the component.
[data-slot="alert"]When to use
Call out a persistent, inline status or message in the page flow — a form-level error, an info notice, a success summary.
Reach for something else when
- A transient, auto-dismissing notification (use sonner/toast)
- a blocking confirm (use alert-dialog)
- a per-field validation message (wire it to the field via form).
Overview
Alert calls out a persistent, inline status or message in the page flow — a form-level error, an info notice, a success summary. The tone sets the intent (info / success / warning / danger), with an optional leading icon, an AlertTitle headline, and an AlertDescription body. It stays in the layout where the user can re-read it; for a transient confirmation that auto-dismisses use a Sonner toast, and for a blocking decision use an AlertDialog.
Guidelines
Match the tone to the real severity. Reserve danger for genuine errors and warning for things that need attention before proceeding; crying wolf with red banners makes people tune them out. One alert per concern beats a stack of competing ones.
Say what happened and what to do. A useful alert names the problem and the next step ("Card declined — try another payment method"), not just "Error". Put a recovery action right in the alert when there's an obvious one.
Place it where the cause is, and announce it. Form-level errors belong at the top of the form or beside the field; the role=alert means it's announced when it appears, so don't render it pre-emptively. Pair color with an icon and text so the meaning survives without color.
Best practices
- Pair a status tone with a text label and an icon — never color alone.
- Use AlertTitle for the headline and AlertDescription for detail.
- Reserve
dangerfor genuine errors; use info/success/warning for non-error status.
- Don't use an Alert for transient toasts — that's sonner.
- Don't rely on the icon/color to carry meaning without text.
- Don't leave an empty Alert mounted (role=alert announces on change).
Content guidelines
- Lead the title with the outcome in a few words (“Payment failed”, “Changes saved”), not bare “Error” / “Success”.
- Use the description for the why and the next step — keep it to a sentence or two.
- Write in plain, calm language; skip blame and exclamation marks, especially for errors.
- Don't repeat the tone in the text (“Error: …”) — the icon and color already carry it.
Troubleshooting
A screen reader doesn't announce the alert.
Cause. role=alert announces when the node appears/changes — mounting it empty and filling it later (or keeping it always present) can swallow the announcement.
Fix. Render the Alert at the moment there's a message, with its text already inside.
Accessibility
- Role
alert
- The container is role=alert — assistive tech announces its text when it appears, so render it when there's something to say (don't keep an empty one mounted).
- Don't encode status by color alone — keep a clear text label; pair the icon with AlertTitle/AlertDescription.