# Alert

**📖 Live documentation:** https://cds.coinbase.com/components/overlay/Alert/

A dialog that communicates critical information and blocks user interaction.

## Import

```tsx
import { Alert } from '@coinbase/cds-web/overlays/Alert'
```

## Examples

:::tip Accessibility tip (Web only)

Alerts require an accessibility label, which we set to `title` by default. However, if there's other text that gives the user better context to the alert, then you can pass an element id to `accessibilityLabelledBy`. Alternatively, you may directly provide a contextual label to `accessibilityLabel`.

:::

### Default Alert

Controlled using `visible` and `onRequestClose`.

```jsx live
function DefaultAlertExample() {
  const [visible, setVisible] = useState(false);

  const toggleOn = () => setVisible(true);
  const toggleOff = () => setVisible(false);

  return (
    <PortalProvider>
      <ButtonGroup>
        <Button onClick={toggleOn}>Show Alert</Button>
      </ButtonGroup>
      <Alert
        title="Alert title"
        body="Alert body type that can run over multiple lines, but should be kept short."
        pictogram="warning"
        visible={visible}
        onRequestClose={toggleOff}
        preferredActionLabel="Primary"
        onPreferredActionPress={() => console.log('preferred pressed')}
        dismissActionLabel="Cancel"
        onDismissActionPress={() => console.log('dismiss pressed')}
      />
    </PortalProvider>
  );
}
```

### Portal Alert

Controlled programmatically using the `useAlert` hook.

:::warning

**Deprecated**: Inserting JSX into the DOM using a function in an event handler is an anti-pattern. This hook will be removed in future version. Use the `visible` and `onRequestClose` props instead

:::

```jsx live
function PortalAlertExample() {
  function PortalAlert() {
    const alert = useAlert();

    const showAlert = () =>
      alert.open(
        <Alert
          title="Alert title"
          body="Alert body type that can run over multiple lines, but should be kept short."
          pictogram="warning"
          visible
          onRequestClose={alert.close}
          preferredActionLabel="Save"
          onPreferredActionPress={() => console.log('Save pressed')}
        />,
      );

    return <Button onClick={showAlert}>Show Alert</Button>;
  }

  return (
    <PortalProvider>
      <PortalAlert />
    </PortalProvider>
  );
}
```

### Alert over Modal

Alert displays on top of a `Modal`. You must pass stacked as a prop to `Alert` when it is used inside of a `Modal`.

```jsx live
function AlertOnModalExample() {
  function AlertOnModal() {
    const { openModal, closeModal } = useModal();
    const alert = useAlert();

    const showAlert = () =>
      alert.open(
        <Alert
          visible
          onRequestClose={alert.close}
          title="Are you sure?"
          body="Cancel will discard your existing changes, are you sure?"
          pictogram="warning"
          preferredActionLabel="Discard"
          onPreferredActionPress={closeModal}
          preferredActionVariant="negative"
          dismissActionLabel="Cancel"
          stacked
        />,
      );

    const handlePress = () => {
      openModal(
        <Modal visible onRequestClose={closeModal}>
          <ModalBody>
            <Text as="p" font="body">
              {loremIpsum}
            </Text>
          </ModalBody>
          <ModalFooter
            primaryAction={<Button onClick={closeModal}>Save</Button>}
            secondaryAction={<Button onClick={showAlert}>Cancel</Button>}
          />
        </Modal>,
      );
    };

    return <Button onClick={handlePress}>Open Modal</Button>;
  }

  return (
    <PortalProvider>
      <AlertOnModal />
    </PortalProvider>
  );
}
```

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `body` | `string` | Yes | `-` | Alert body/description |
| `onRequestClose` | `() => void` | Yes | `-` | Callback function fired when modal is closed. |
| `preferredActionLabel` | `string` | Yes | `-` | Label of the preferred action |
| `title` | `string` | Yes | `-` | Alert title |
| `visible` | `boolean` | Yes | `false false` | Controls visibility of the Modal |
| `accessibilityLabelledBy` | `string` | No | `-` | On web, maps to aria-labelledby and lists the id(s) of the element(s) that label the element on which the attribute is set. On mobile (Android only), a reference to another element nativeID used to build complex forms. |
| `actionLayout` | `horizontal \| vertical` | No | `horizontal` | Layout of the actions |
| `disablePortal` | `boolean` | No | `-` | Disable React portal integration |
| `dismissActionLabel` | `string` | No | `-` | Label of the dismiss action |
| `key` | `Key \| null` | No | `-` | - |
| `onDidClose` | `((() => void) & (() => void))` | No | `-` | Callback fired after the component is closed. |
| `onDismissActionPress` | `(() => void)` | No | `-` | Callback function fired when the dismiss action is pressed |
| `onPreferredActionPress` | `(() => void)` | No | `-` | Callback function fired when the preferred action is pressed |
| `pictogram` | `PictogramName` | No | `-` | Illustration pictogram name for alert |
| `preferredActionVariant` | `primary \| negative` | No | `primary` | Button variant of the preferred action |
| `ref` | `((instance: ModalRefBaseProps \| null) => void) \| RefObject<ModalRefBaseProps> \| null` | No | `-` | - |
| `stacked` | `boolean` | No | `-` | Indicating if Alert is stacked on top of Modal |
| `testID` | `string` | No | `-` | Used to locate this element in unit and end-to-end tests. Under the hood, testID translates to data-testid on Web. On Mobile, testID stays the same - testID |