# Alert

A notice that stands out from the page to tell the reader something important.

```tsx
import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"
import { VStack } from "@/components/ui/stack"
import { CheckCircleIcon } from "@phosphor-icons/react/dist/csr/CheckCircle"
import { InfoIcon } from "@phosphor-icons/react/dist/csr/Info"
import { widths } from "@/theme/widths"

export default function AlertDemo() {
  return (
    <VStack gap={4} xstyle={widths.md}>
      <Alert variant="success">
        <CheckCircleIcon aria-hidden="true" />
        <AlertTitle>Invoice paid</AlertTitle>
        <AlertDescription>
          We charged $29.99 to your card and sent the receipt to your billing email.
        </AlertDescription>
      </Alert>
      <Alert variant="info">
        <InfoIcon aria-hidden="true" />
        <AlertTitle>Version history is here</AlertTitle>
        <AlertDescription>
          Open any document and choose History to restore an earlier draft.
        </AlertDescription>
      </Alert>
    </VStack>
  )
}
```

## Installation

**Command**

```bash
npx shadcn@latest add @arene/alert
```

Needs the [arene setup](https://www.arene.style/docs/installation) first.

**Manual**

1. Install the packages it imports:

   ```bash
   npm install @base-ui/react @stylexjs/stylex clsx
   ```

2. Set up the token layer and the StyleX compiler, if you have not already. See
   [Installation](https://www.arene.style/docs/installation). The alert also needs `interop.css`, which
   places the icon and sizes it.

3. Paste this source into the file named in its title.

   ```tsx title="components/ui/alert.tsx"
   "use client"

   import { useRender } from "@base-ui/react/use-render"
   import * as stylex from "@stylexjs/stylex"
   import type { StyleXStyles } from "@stylexjs/stylex"
   import { clsx } from "clsx"

   import { breakpoints } from "@/theme/breakpoints.stylex"
   import { color, leading, radius, space, text } from "@/theme/tokens.stylex"

   const styles = stylex.create({
     root: {
       display: "grid",
       gridTemplateColumns: "auto 1fr auto",
       rowGap: space.s0_5,
       width: "100%",
       paddingInline: space.s4,
       paddingBlock: space.s3,
       borderRadius: radius.lg,
       borderWidth: 1,
       borderStyle: "solid",
       color: color.foreground,
       textAlign: "start",
       fontSize: text.sm,
       lineHeight: leading.sm,
       "--arene-icon-size": space.s4,
     },
     title: { gridColumn: "2", fontWeight: 500 },
     description: {
       gridColumn: "2",
       color: color.mutedForeground,
       textWrap: { default: "balance", [breakpoints.md]: "pretty" },
     },
     action: {
       gridColumn: "3",
       gridRowStart: "1",
       gridRowEnd: "span 2",
       alignSelf: "start",
       marginInlineStart: space.s2,
     },
   })

   const variants = stylex.create({
     default: {
       borderColor: color.border,
       backgroundColor: color.card,
       "--arene-alert-accent": color.foreground,
     },
     info: {
       borderColor: color.infoBorder,
       backgroundColor: color.infoBg,
       "--arene-alert-accent": color.info,
     },
     success: {
       borderColor: color.successBorder,
       backgroundColor: color.successBg,
       "--arene-alert-accent": color.success,
     },
     warning: {
       borderColor: color.warningBorder,
       backgroundColor: color.warningBg,
       "--arene-alert-accent": color.warning,
     },
     destructive: {
       borderColor: `color-mix(in oklab, ${color.destructive} 30%, transparent)`,
       backgroundColor: `color-mix(in oklab, ${color.destructive} 6%, transparent)`,
       "--arene-alert-accent": color.destructive,
     },
   })

   const alertStyles = { base: styles.root, variants }

   type AlertVariant = keyof typeof variants

   type Overrides = { xstyle?: StyleXStyles; className?: string }

   type AlertProps = useRender.ComponentProps<"div"> & Overrides & { variant?: AlertVariant }

   function Alert({
     render,
     ref,
     style,
     variant = "default",
     xstyle,
     className,
     ...props
   }: AlertProps) {
     const sx = stylex.props(styles.root, variants[variant] ?? variants.default, xstyle)
     return useRender({
       defaultTagName: "div",
       render,
       ref,
       props: {
         "data-slot": "alert",
         "data-variant": variant,
         role: "alert",
         ...sx,
         ...props,
         className: clsx("arene-icons", sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   function AlertTitle({
     render,
     ref,
     style,
     xstyle,
     className,
     ...props
   }: useRender.ComponentProps<"div"> & Overrides) {
     const sx = stylex.props(styles.title, xstyle)
     return useRender({
       defaultTagName: "div",
       render,
       ref,
       props: {
         "data-slot": "alert-title",
         ...sx,
         ...props,
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   function AlertDescription({
     render,
     ref,
     style,
     xstyle,
     className,
     ...props
   }: useRender.ComponentProps<"div"> & Overrides) {
     const sx = stylex.props(styles.description, xstyle)
     return useRender({
       defaultTagName: "div",
       render,
       ref,
       props: {
         "data-slot": "alert-description",
         ...sx,
         ...props,
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   function AlertAction({
     render,
     ref,
     style,
     xstyle,
     className,
     ...props
   }: useRender.ComponentProps<"div"> & Overrides) {
     const sx = stylex.props(styles.action, xstyle)
     return useRender({
       defaultTagName: "div",
       render,
       ref,
       props: {
         "data-slot": "alert-action",
         ...sx,
         ...props,
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   export { Alert, AlertAction, AlertDescription, AlertTitle, alertStyles, type AlertVariant }
   ```

4. Change the `@/` imports if your project uses different aliases.

## Usage

```tsx
import { Alert, AlertAction, AlertDescription, AlertTitle } from "@/components/ui/alert"
```

```tsx
<Alert>
  <InfoIcon />
  <AlertTitle>Two-step sign-in</AlertTitle>
  <AlertDescription>Ask for a code from your phone when you sign in.</AlertDescription>
  <AlertAction>
    <Button variant="outline">Enable</Button>
  </AlertAction>
</Alert>
```

## Composition

```text
Alert
├── Icon
├── AlertTitle
├── AlertDescription
└── AlertAction
```

The icon is any `svg` passed as a direct child. The alert is a three-column
grid, and `interop.css` places the icon in the first column and the action in
the last. Both columns collapse to nothing when empty.

## Basic

The default variant with an icon, a title and a description.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"
import { CheckCircleIcon } from "@phosphor-icons/react/dist/csr/CheckCircle"
import { width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  alert: { maxWidth: width.md },
})

export default function AlertBasic() {
  return (
    <Alert xstyle={styles.alert}>
      <CheckCircleIcon aria-hidden="true" />
      <AlertTitle>Preferences saved</AlertTitle>
      <AlertDescription>
        Your notification settings now apply to every project in this workspace.
      </AlertDescription>
    </Alert>
  )
}
```

## Variants

Use the `variant` prop to set the tone: `default`, `info`, `success`, `warning`
or `destructive`. Each is a flat tinted fill with a matching border, and the
icon takes the variant's accent colour. The title and description keep the
page's own text colours, so every variant reads the same way.

```tsx
import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"
import { VStack } from "@/components/ui/stack"
import { CheckCircleIcon } from "@phosphor-icons/react/dist/csr/CheckCircle"
import { InfoIcon } from "@phosphor-icons/react/dist/csr/Info"
import { NotePencilIcon } from "@phosphor-icons/react/dist/csr/NotePencil"
import { WarningCircleIcon } from "@phosphor-icons/react/dist/csr/WarningCircle"
import { WarningIcon } from "@phosphor-icons/react/dist/csr/Warning"
import { widths } from "@/theme/widths"

export default function AlertVariants() {
  return (
    <VStack gap={3} xstyle={widths.md}>
      <Alert>
        <NotePencilIcon aria-hidden="true" />
        <AlertTitle>Drafts save automatically</AlertTitle>
        <AlertDescription>Changes are kept for 30 days before they are discarded.</AlertDescription>
      </Alert>
      <Alert variant="info">
        <InfoIcon aria-hidden="true" />
        <AlertTitle>Maintenance on Sunday</AlertTitle>
        <AlertDescription>
          The dashboard will be read-only from 02:00 to 03:00 UTC.
        </AlertDescription>
      </Alert>
      <Alert variant="success">
        <CheckCircleIcon aria-hidden="true" />
        <AlertTitle>Domain verified</AlertTitle>
        <AlertDescription>Email from example.com will now be delivered.</AlertDescription>
      </Alert>
      <Alert variant="warning">
        <WarningIcon aria-hidden="true" />
        <AlertTitle>Your trial ends in 3 days</AlertTitle>
        <AlertDescription>Add a payment method to keep your projects running.</AlertDescription>
      </Alert>
      <Alert variant="destructive">
        <WarningCircleIcon aria-hidden="true" />
        <AlertTitle>Payment failed</AlertTitle>
        <AlertDescription>Check your payment method and try again.</AlertDescription>
      </Alert>
    </VStack>
  )
}
```

## Action

Put a button in `AlertAction`. It sits in the alert's last column, beside the text.

```tsx
import * as stylex from "@stylexjs/stylex"
import { Alert, AlertAction, AlertDescription, AlertTitle } from "@/components/ui/alert"
import { Button } from "@/components/ui/button"
import { width } from "@/theme/tokens.stylex"

const styles = stylex.create({
  alert: { maxWidth: width.md },
})

export default function AlertActionDemo() {
  return (
    <Alert xstyle={styles.alert}>
      <AlertTitle>Offline editing is available</AlertTitle>
      <AlertDescription>Turn it on to keep writing when your connection drops.</AlertDescription>
      <AlertAction>
        <Button size="xs">Enable</Button>
      </AlertAction>
    </Alert>
  )
}
```

## API reference

Pass `render` to replace a part's element or compose it with another component.

### Alert

Renders a `div` with `role="alert"`, which a screen reader announces as soon as
it appears. For a notice that is part of the page, such as a note in an article,
pass `role="note"` instead. Every part also takes `xstyle` and `className`.

| Prop      | Type                                                             | Default     |
| --------- | ---------------------------------------------------------------- | ----------- |
| `variant` | `"default" \| "info" \| "success" \| "warning" \| "destructive"` | `"default"` |

### alertStyles

The style map behind the component, exported so you can apply the same styles
to any element.

| Key        | Description                                |
| ---------- | ------------------------------------------ |
| `base`     | The grid, padding, border width and type   |
| `variants` | One entry per `variant`, keyed by its name |

### Data attributes

| Attribute                       | On              | Effect                                        |
| ------------------------------- | --------------- | --------------------------------------------- |
| `data-slot="alert"`             | the root        | Where `interop.css` keys the icon's grid slot |
| `data-variant`                  | the root        | Reflects the `variant` prop                   |
| `data-slot="alert-title"`       | the title       | Links inside are underlined by `interop.css`  |
| `data-slot="alert-description"` | the description | Links inside are underlined by `interop.css`  |
| `data-slot="alert-action"`      | the action      | Targets the action from a parent              |

### CSS variables

| Variable               | On       | Effect                                                       |
| ---------------------- | -------- | ------------------------------------------------------------ |
| `--arene-alert-accent` | the root | The icon's colour. Set by the variant, read by `interop.css` |
