# React Native Alert

> An accessible React Native alert banner for iOS, Android and the web: a title and description in default, success, warning and destructive variants, announced to screen readers when it appears. Use it as one element with props, or compose the parts.

# Alert

A banner that tells the user something about the page, such as a failed payment or a saved change. It's part of the page, not a dialog.

```tsx
import { Alert, AlertDescription, AlertTitle } from 'patine-ui';
```

The quickest way: give `Alert` a `title` and a `description`. Children, if any, follow them.

```tsx live
import { Alert } from 'patine-ui';

export default function Example() {
  return <Alert variant="destructive" title="Payment failed" description="Your card was declined. Try another one." />;
}
```

## Compose the parts

For full control, leave those props out and compose `AlertTitle` and `AlertDescription`.

```tsx live
import { Alert, AlertDescription, AlertTitle } from 'patine-ui';

export default function Example() {
  return (
    <Alert>
      <AlertTitle>Heads up</AlertTitle>
      <AlertDescription>You can add components to your app with the CLI.</AlertDescription>
    </Alert>
  );
}
```

## Example: a failed payment

A billing page: the renewal failed, so a destructive alert explains what happens next and offers the fix. Updating the card swaps it for a success alert.

```tsx live
import { useState } from 'react';
import { Alert, AlertDescription, AlertTitle, Button, Card, CardContent, HStack, Text, VStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  const [state, setState] = useState<'failed' | 'updating' | 'paid'>('failed');
  const retry = () => {
    setState('updating');
    setTimeout(() => setState('paid'), 1200);
  };
  return (
    <VStack gap="md" style={{ width: '100%', maxWidth: 480 }}>
      {state === 'paid' ? (
        <Alert variant="success" icon={<Icon name="checkCircle" color="success" />} title="Payment received" description="€49.00 charged to Visa •••• 0119. Your Team plan renews on December 3." />
      ) : (
        <Alert variant="destructive" icon={<Icon name="card" color="danger" />}>
          <AlertTitle>Your November payment failed</AlertTitle>
          <AlertDescription>Mastercard •••• 4417 expired. We'll try again on November 21; after that the workspace becomes read-only.</AlertDescription>
          <HStack gap="sm" wrap style={{ marginTop: 12 }}>
            <Button size="sm" variant="destructive" loading={state === 'updating'} onPress={retry}>
              Update card
            </Button>
            <Button size="sm" variant="ghost">View invoice</Button>
          </HStack>
        </Alert>
      )}
      <Card>
        <CardContent style={{ gap: 4 }}>
          <Text weight="semibold">Team plan</Text>
          <Text color="textSecondary">8 seats · €49.00 a month</Text>
        </CardContent>
      </Card>
    </VStack>
  );
}
```

## Variants

```tsx live
import { Alert, AlertDescription, AlertTitle, VStack } from 'patine-ui';

export default function Example() {
  return (
    <VStack gap="md">
      <Alert variant="success" live={false}>
        <AlertTitle>Payment received</AlertTitle>
        <AlertDescription>Your licence is on its way.</AlertDescription>
      </Alert>
      <Alert variant="warning" live={false}>
        <AlertTitle>Your trial ends in 3 days</AlertTitle>
        <AlertDescription>Add a card to keep your projects.</AlertDescription>
      </Alert>
      <Alert variant="destructive" live={false}>
        <AlertTitle>Payment failed</AlertTitle>
        <AlertDescription>Check your card details and try again.</AlertDescription>
      </Alert>
    </VStack>
  );
}
```

## With an icon

`icon` takes any node and sits before the text, such as an icon from your icon set.

```tsx live
import { Alert, VStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  return (
    <VStack gap="md">
      <Alert icon={<Icon name="info" color="primary" />} title="Scheduled maintenance" description="The dashboard is read-only on Sunday from 02:00 to 04:00 UTC." />
      <Alert variant="success" live={false} icon={<Icon name="checkCircle" color="success" />} title="Domain verified" description="acme.com now sends email from your workspace." />
      <Alert variant="warning" live={false} icon={<Icon name="alert" color="warning" />} title="You've used 92% of your storage" description="Free up space or upgrade before uploads stop." />
    </VStack>
  );
}
```

## With actions

Put buttons in the alert's children, after the description, for the next step.

```tsx live
import { Alert, AlertDescription, AlertTitle, Button, HStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  return (
    <Alert variant="destructive" live={false} icon={<Icon name="card" color="danger" />}>
      <AlertTitle>Your card was declined</AlertTitle>
      <AlertDescription>We'll retry on March 3. Update your card to keep your Pro plan active.</AlertDescription>
      <HStack gap="sm" style={{ marginTop: 12 }}>
        <Button size="sm" variant="destructive">Update card</Button>
        <Button size="sm" variant="ghost">Contact billing</Button>
      </HStack>
    </Alert>
  );
}
```

## Dismissible

An alert has no close button of its own: add one, and keep whether it's closed in your state.

```tsx live
import { useState } from 'react';
import { Alert, Button, HStack, Text, VStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  const [open, setOpen] = useState(true);
  if (!open) return <Button variant="outline" onPress={() => setOpen(true)} style={{ alignSelf: 'flex-start' }}>Show the banner again</Button>;
  return (
    <Alert icon={<Icon name="sparkles" color="primary" />}>
      <HStack gap="sm" align="flex-start">
        <VStack gap="xs" style={{ flex: 1 }}>
          <Text weight="semibold">Patine 2.0 is here</Text>
          <Text color="textSecondary">Charts, a data grid and twelve new screens.</Text>
        </VStack>
        <Button size="icon" variant="ghost" accessibilityLabel="Dismiss" onPress={() => setOpen(false)}>
          <Icon name="x" />
        </Button>
      </HStack>
    </Alert>
  );
}
```

## After an action

An error that comes back from a request should be announced. A `destructive` alert is `live` by default, so a screen reader reads it as soon as it appears.

```tsx live
import { useState } from 'react';
import { Alert, Button, TextField, VStack } from 'patine-ui';

export default function Example() {
  const [error, setError] = useState(false);
  const [busy, setBusy] = useState(false);
  const signIn = () => {
    setBusy(true);
    setError(false);
    setTimeout(() => {
      setBusy(false);
      setError(true);
    }, 900);
  };
  return (
    <VStack gap="md" style={{ maxWidth: 380 }}>
      {error ? <Alert variant="destructive" title="Wrong email or password" description="Check them and try again, or reset your password." /> : null}
      <TextField label="Email" defaultValue="maya@example.com" autoCapitalize="none" />
      <TextField label="Password" secureTextEntry defaultValue="hunter2" />
      <Button loading={busy} onPress={signIn}>Sign in</Button>
    </VStack>
  );
}
```

## Designs

```tsx live
import { Alert, VStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

const DESIGNS = { brand: 'Brand', ios: 'iOS', material: 'Material', web: 'Web' } as const;

export default function Example() {
  return (
    <VStack gap="sm">
      {Object.entries(DESIGNS).map(([design, label]) => (
        <Alert key={design} design={design as keyof typeof DESIGNS} variant="warning" live={false} icon={<Icon name="alert" color="warning" />} title={label} description="Your trial ends in 3 days." />
      ))}
    </VStack>
  );
}
```

## Accessibility

- A `destructive` alert, or any alert with `live`, is announced as soon as it appears: through the screen reader on iOS and Android, and as `role="alert"` on the web. Use it for errors that come after an action.
- Other alerts are read in place, like the rest of the page. Set `live={false}` on a destructive alert that's there from the start.
- The variant's color isn't the only signal: write the status in the title.

## Props

Alert also takes `View` props. `AlertTitle` and `AlertDescription` take `Text` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'default' \| 'destructive' \| 'success' \| 'warning'` | `'default'` | The look. |
| `icon` | `ReactNode` | — | Shown before the title and description. |
| `title` | `ReactNode` | — | Shorthand: the `AlertTitle`. |
| `description` | `ReactNode` | — | Shorthand: the `AlertDescription`. |
| `live` | `boolean` | `true` for `destructive` | Announce it as soon as it appears. |
| `theme` | `DeepPartial<Theme>` | — | Theme override. |
| `design` | `'brand' \| 'ios' \| 'material' \| 'web' \| 'native'` | from `PatineProvider` | The look to follow: [brand, iOS, Material or web](../guides/designs), or `'native'` for the platform's own. |
