# Alert

A message about the page or the work that stays where it is until it no longer applies: a warning before a change, a note that something failed, a fact the person should know. Put an icon first, then `AlertTitle` and `AlertDescription`. Its text is plain text from the app, never HTML. An `Alert` is read out when it appears if its variant is `destructive` (role "alert"); the other variants are polite (role "status"). Pass `role` to change that. For a short notice that goes away by itself use a toast; an Alert doesn't dismiss itself.

- Registry name: `alert` (`@candor/alert`)
- Tier: Free (MIT). No licence key needed.
- Docs: https://candor.themethodic.com/docs/alert

## Install

```bash
npx candor-ui add alert
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/alert`.
It brings in: motion, tokens, utils.
npm packages: class-variance-authority@^0.7.1.

## Example

```tsx
"use client"

import { CircleAlert, Info, TriangleAlert } from "lucide-react"
import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"

export default function Example() {
  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <Alert>
        <Info aria-hidden />
        <AlertTitle>This run is read-only</AlertTitle>
        <AlertDescription>It can look at the records but can't change them.</AlertDescription>
      </Alert>
      <Alert variant="warning">
        <TriangleAlert aria-hidden />
        <AlertTitle>The next step can't be undone</AlertTitle>
        <AlertDescription>Deleting the archive removes 214 files. There is no recovery.</AlertDescription>
      </Alert>
      <Alert variant="destructive">
        <CircleAlert aria-hidden />
        <AlertTitle>The import stopped</AlertTitle>
        <AlertDescription>The service answered with an error after 40 of 120 records. Nothing after record 40 was written.</AlertDescription>
      </Alert>
    </div>
  )
}
```

## <Alert>

Props:

- `variant?: "default" | "success" | "warning" | "attention" | "destructive" | null | undefined`: The kind of message. `destructive` is for a failure or something that can't be undone; `warning` for care before acting; `attention` for something waiting on the person; `success` for a confirmed result. Defaults to a plain card.

Also takes the props of `React.ComponentProps<"div">`.

## <AlertTitle>

The alert's headline: what happened or what to know, in a few words.

No props.

Also takes the props of `React.ComponentProps<"div">`.

## <AlertDescription>

The detail under the title: what it affects and what the person can do. Plain text or any elements; links and buttons keep their own styles.

No props.

Also takes the props of `React.ComponentProps<"div">`.

## Motion

- **enter** (arrive, rise): An Alert that appears after the page has drawn rises in over a quarter of a second. One that is there when the page first draws, or that the server rendered, is simply there; after a client-side navigation, an Alert on the new route rises in.

Set with `--cd-motion-alert-<moment>-*` in your brand file; the families are in the design reference.

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.