# Alert

Shows an inline message tied to nearby content.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Alert.tsx)

Figma: [Alert](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=3056-453)

## Overview

An inline message on a tinted container, with a square indicator in the color of its `intent`. It is a live region, so screen readers announce it when it appears.

## Examples

### Basic

```tsx
import { Alert } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Alert>
      <Alert.Icon />
      <Alert.Content>Changes may take a few minutes to appear.</Alert.Content>
    </Alert>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Alert/Basic.tsx)

### Intent

Set `intent` to `neutral` (default), `positive`, `warning`, `negative`, `tip`, or `special`.

```tsx
import { Alert, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      {(['neutral', 'positive', 'warning', 'negative', 'tip', 'special'] as const).map((intent) => (
        <Alert intent={intent} key={intent}>
          <Alert.Icon />
          <Alert.Content>You need to deposit $25.00 to continue.</Alert.Content>
        </Alert>
      ))}
    </div>
  )
}

namespace styles {
  export const stack = style({
    display: 'flex',
    flexDirection: 'column',
    gap: '12',
    maxWidth: '36rem !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Alert/Intent.tsx)

### Title and Action

Add an `Alert.Title` above the message, and an `Alert.Action` after it, inside `Alert.Content`.

```tsx
import { Alert, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Alert intent="warning" {...styles.note()}>
      <Alert.Icon />
      <Alert.Content>
        <Alert.Title>New address</Alert.Title>
        Check the first and last 4 characters.
        <Alert.Action>View details</Alert.Action>
      </Alert.Content>
    </Alert>
  )
}

namespace styles {
  export const note = style({ maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Alert/Title.tsx)

### Inline

The content flows as text, so inline elements such as `strong` stay on the lines of the message.

```tsx
/** Renders a warning whose message holds inline `strong` text, for the Alert docs. @module */
import { Alert } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Alert intent="warning" role="note">
      <Alert.Icon />
      <Alert.Content>
        Only send <strong>supported stablecoins</strong> on <strong>Tempo</strong>. Sending other
        tokens or using a different network may result in permanent loss.
      </Alert.Content>
    </Alert>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Alert/Inline.tsx)

### Dismiss

Add an `Alert.Dismiss` after `Alert.Content`. Remove the alert in its `onClick`.

```tsx
import { Alert, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Alert intent="tip" {...styles.note()}>
      <Alert.Icon />
      <Alert.Content>
        <Alert.Title>Fee token</Alert.Title>
        Fees are paid in USDC. Change it in Settings.
      </Alert.Content>
      <Alert.Dismiss />
    </Alert>
  )
}

namespace styles {
  export const note = style({ maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Alert/Dismiss.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Alert } from '@tempoxyz/ds'

<Alert>
  <Alert.Icon />
  <Alert.Content>
    <Alert.Title />
    <Alert.Action />
  </Alert.Content>
  <Alert.Dismiss />
</Alert>
```

## Guidelines

### When to Use

* Explain a condition that affects nearby content, such as higher network fees above the Send payment form.
* Keep a result visible beside its section, such as a failed webhook delivery.
* Give guidance before a task, such as a note that testnet tokens have no value.
* Add optional context with `tip`, such as the token that pays network fees.

### When Not to Use

* Use [Banner](/docs/components/banner) for a message about the whole product or page, such as an outage.
* Use [Toast](/docs/components/toast) to confirm that an action finished, such as Payment sent.
* If an action needs a decision before it continues, use [AlertDialog](/docs/components/alert-dialog).
* Use `Field.Error` from [Field](/docs/components/field) for a validation message on one input.
* Use [Badge](/docs/components/badge) for a one-word status on a table row or card, such as Pending.

### Choose an Intent by Severity

* **Neutral (default):** Context that needs no action, such as when deposits confirm.
* **Positive (positive):** A result that stays in place, such as a verified webhook endpoint.
* **Warning (warning):** An avoidable risk, such as sending to an address new to Tempo.
* **Negative (negative):** A blocking failure, such as balances that couldn't load.
* **Tip (tip):** Optional context, such as the token that pays the network fee.
* **Special (special):** A new feature to announce, such as vaults for idle USDC balances.

Use `warning` before a risky step and `negative` before one that can't be undone. Never use `positive` as decoration.

### Pair the Icon With Text That States the Outcome

Add `Alert.Icon` to every alert. It draws a square in the color of the intent.

**Do:** Combine `Alert.Icon` with a sentence that names the condition.

```tsx
/**
 * Do example for "Pair the Icon With Text That States the Outcome" on the Alert page.
 * Combine `Alert.Icon` with a sentence that names the condition.
 * @module
 */
import { Alert } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Alert intent="warning">
      <Alert.Icon />
      <Alert.Content>
        Network fees are higher than usual.
        <Alert.Action>Review fees</Alert.Action>
      </Alert.Content>
    </Alert>
  )
}
```

**Don't:** Leave out the icon or let the tint carry the warning.

```tsx
/**
 * Don't example for "Pair the Icon With Text That States the Outcome" on the Alert page.
 * Don't leave out the icon or let the tint carry the warning.
 * @module
 */
import { Alert } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Alert intent="warning">
      <Alert.Content>
        Network fees
        <Alert.Action>Review</Alert.Action>
      </Alert.Content>
    </Alert>
  )
}
```

### Place It Beside What It Describes

Remove the alert when its condition ends, such as when fees return to normal. In a [Dialog](/docs/components/dialog), show one alert at full width, below the input it describes.

**Do:** Put the alert directly above the form it describes, or directly below its control.

```tsx
/**
 * Do example for "Place It Beside What It Describes" on the Alert page.
 * Put the callout directly above the form it describes, or directly below its control.
 * @module
 */
import { Alert, Button, Field, Stack, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Stack gap="16" {...styles.fill()}>
      <div {...styles.activity()}>
        <div {...styles.heading()}>Recent activity</div>
        <div>Sent 25.00 USDC to 0x8f3c…a21b</div>
        <div>Received 120.00 USDC from 0x41d0…9c7e</div>
      </div>
      <Alert intent="warning">
        <Alert.Icon />
        <Alert.Content>Network fees are higher than usual.</Alert.Content>
      </Alert>
      <Field.Root>
        <Field.Label>Amount</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="50.00" />
        </TextInput.Group>
      </Field.Root>
      <Button>Send payment</Button>
    </Stack>
  )
}

namespace styles {
  export const activity = style({
    color: 'content.secondary',
    display: 'flex',
    flexDirection: 'column',
    gap: '4',
    typography: 'body.b2',
  })

  export const fill = style({ width: '100% !custom' })

  export const heading = style({ color: 'content.primary', typography: 'body.b2' })
}
```

**Don't:** Place it at the top of a long page, away from its content.

```tsx
/**
 * Don't example for "Place It Beside What It Describes" on the Alert page.
 * Don't place it at the top of a long page, away from its content.
 * @module
 */
import { Alert, Button, Field, Stack, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Stack gap="16" {...styles.fill()}>
      <Alert intent="warning">
        <Alert.Icon />
        <Alert.Content>Network fees are higher than usual.</Alert.Content>
      </Alert>
      <div {...styles.activity()}>
        <div {...styles.heading()}>Recent activity</div>
        <div>Sent 25.00 USDC to 0x8f3c…a21b</div>
        <div>Received 120.00 USDC from 0x41d0…9c7e</div>
      </div>
      <Field.Root>
        <Field.Label>Amount</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="50.00" />
        </TextInput.Group>
      </Field.Root>
      <Button>Send payment</Button>
    </Stack>
  )
}

namespace styles {
  export const activity = style({
    color: 'content.secondary',
    display: 'flex',
    flexDirection: 'column',
    gap: '4',
    typography: 'body.b2',
  })

  export const fill = style({ width: '100% !custom' })

  export const heading = style({ color: 'content.primary', typography: 'body.b2' })
}
```

### Offer One Action

For more options than one action, link to a page that explains them.

**Do:** Offer the one action that resolves the message.

```tsx
/** Do example for "Offer One Action" on the Alert page: offer the one action that resolves the message. @module */
import { Alert } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Alert intent="negative">
      <Alert.Icon />
      <Alert.Content>
        <Alert.Title>Webhook delivery failed</Alert.Title>
        Your endpoint returned 500.
        <Alert.Action>Retry</Alert.Action>
      </Alert.Content>
    </Alert>
  )
}
```

**Don't:** Line up several actions inside one alert.

```tsx
/**
 * Don't example for "Offer One Action" on the Alert page.
 * Don't line up several actions inside one callout.
 * @module
 */
import { Alert } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Alert intent="negative">
      <Alert.Icon />
      <Alert.Content>
        Webhook delivery failed.
        <Alert.Action>Retry</Alert.Action>
        <Alert.Action>Logs</Alert.Action>
        <Alert.Action>Docs</Alert.Action>
      </Alert.Content>
    </Alert>
  )
}
```

To link elsewhere, pass `Alert.Action` a `render` with an `a` element and `nativeButton={false}`.

## Content

* Lead with the condition, then the consequence or next step: Network fees are higher than usual. Your payment may take longer to confirm.
* Keep it to one or two sentences. Add an `Alert.Title` of two or three words, such as New address, when the message needs a label.
* Describe the condition, not the intent. Write Webhook delivery failed, not Error.
* Use specific values, such as the amount needed: You need to deposit $25.00 to continue.
* Start the action label with a verb, such as Review fees or Add funds.

## Accessibility

An alert is a live region whose role depends on `intent`. It does not move focus when it appears.

### Semantics

* **Neutral, Positive, Tip, and Special (status):** Announced at the next pause.
* **Warning and Negative (alert):** Interrupts the screen reader.
* **Role Override (role):** Replaces either default, such as `role="note"` for static text.
* **Alert.Icon (aria-hidden):** Never announced. The text carries the meaning.
* **Alert.Action (button):** A native button. Enter and Space activate it.
* **Contrast (content.primary):** Text stays primary on every tint and scheme. Keep the background.

### Keyboard

* **Move to the Action (Tab):** Moves focus to the alert's action, if any.
* **Activate the Action (Enter or Space):** Activates the action.

### Your Responsibilities

* **Reserve Assertive Intents (warning or negative):** They interrupt the screen reader, so use them only for a message the reader must act on.
* **Insert It When the Condition Occurs:** An alert present on first render may not be announced. Insert it after the failed request.
* **Render the Region First:** If one alert shows several messages, render the live region before you change its content.
* **Remove It on Dismiss (onClick):** `Alert.Dismiss` only renders the button. Remove the alert and move focus in `onClick`.

## Related

[Banner](/docs/components/banner)

Use for a message about the whole page.

[Toast](/docs/components/toast)

Use for confirming a finished action.

[Field](/docs/components/field)

Use for validation messages on an input.

[Errors and Validation](/docs/patterns/errors-and-validation)

Covers reporting failures.

[Feedback and Status](/docs/patterns/feedback-and-status)

Covers choosing a message component.
