# 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, 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 when it is rendered on the server, is simply there. "After the page has drawn" is counted from when the page loaded, not from the route: 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`.