# Alert

> An inline message about the state of a page or section, in four tones.

Category: Feedback · Status: stable · Package: @bindshq/stance-react@0.1.1 · Docs: https://stanceui.com/components/alert

Alert sits in the content flow, near what it describes, and stays until the situation changes or the user dismisses it. Use it for form-level errors, expiring connections or plan limits. For page-wide announcements use Banner; for transient confirmations use Toast.

## Import

```tsx
import { Alert } from '@bindshq/stance-react';
```

Styles are imported once per app: `@bindshq/stance-tokens/css` and `@bindshq/stance-react/styles.css`.

## Examples

### Basic

```tsx
import { Alert } from '@bindshq/stance-react';

export function Basic() {
  return (
    <Alert title="Signatures update overnight">
      Changes you publish today reach every mailbox after the 02:00 sync.
    </Alert>
  );
}
```

### Tones

```tsx
import { Alert } from '@bindshq/stance-react';

export function Tones() {
  return (
    <div style={{ display: 'grid', gap: 12 }}>
      <Alert tone="info" title="Directory sync is on">
        New starters receive the default signature automatically.
      </Alert>
      <Alert tone="success" title="Exchange connected">
        Signatures will deploy through your relay.
      </Alert>
      <Alert tone="warning" title="48 of 50 seats used">
        Add seats before inviting more people.
      </Alert>
      <Alert tone="danger" title="Deployment failed">
        Exchange rejected the connection. Check your relay credentials.
      </Alert>
    </div>
  );
}
```

### With actions

```tsx
import { Alert, Button } from '@bindshq/stance-react';

export function WithActions() {
  return (
    <Alert
      tone="warning"
      title="Azure connection expires in 3 days"
      actions={
        <>
          <Button size="sm">Reconnect</Button>
          <Button size="sm" variant="ghost">
            Remind me later
          </Button>
        </>
      }
    >
      Signatures stop deploying when the token expires.
    </Alert>
  );
}
```

### Dismissible

```tsx
import * as React from 'react';
import { Alert, Button } from '@bindshq/stance-react';

export function Dismissible() {
  const [open, setOpen] = React.useState(true);
  return open ? (
    <Alert tone="success" title="Import complete" onDismiss={() => setOpen(false)}>
      120 users were added to your organisation.
    </Alert>
  ) : (
    <Button variant="outline" size="sm" onClick={() => setOpen(true)}>
      Show again
    </Button>
  );
}
```

## API reference

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Alert | `tone` | `'info' \| 'success' \| 'warning' \| 'danger'` | `'info'` | Meaning of the message. |
| Alert | `title` | `ReactNode` | None | Short heading. |
| Alert | `children` | `ReactNode` | None | Description. |
| Alert | `icon` | `ReactNode \| false` | None | Replace the tone icon or hide it. |
| Alert | `actions` | `ReactNode` | None | Buttons or links under the message. |
| Alert | `onDismiss` | `() => void` | None | Shows a dismiss button. |
| Alert | `dismissLabel` | `string` | `'Dismiss'` | Dismiss button label. |
| Alert | `role` | `AriaRole` | None | Override the automatic role (alert for warning/danger, status otherwise). |

## Accessibility

- Warning and danger alerts use role="alert" and are announced immediately; info and success use role="status".
- Tone is conveyed by icon and title text, never colour alone.
- Status colours meet 4.5:1 contrast in all three themes; high contrast adds heavier borders.

## Guidelines

**Do**

- Say what happened and what to do next.
- Place the alert next to the content it concerns.

**Don’t**

- Render role="alert" messages on page load for non-urgent information.
- Stack several alerts; combine them.

## Related

- https://stanceui.com/components/banner
- https://stanceui.com/components/toast
- https://stanceui.com/components/form-field