# Notification
> Represents a highlighted message that calls out important information.

<Callout variant="tip">

Don't confuse notifications with [live, event-driven Toaster messages](/components/toaster), which show up as feedback about an action triggered by an user and float above the view to disappear after a few seconds.
Notifications are typically not user-initiated and provide contextual static information.

</Callout>

## Import

```js
import { Notification } from '@gemini-suite/vera-react';

// you may also access Notification context via hook:
// import { useNotificationContext } from '@gemini-suite/vera-react';
```

Notification is a compound component that consists of multiple parts:

- `Notification.Root`: The wrapper that contains all the parts of a notification.
- `Notification.Actions`: A wrapper for action(s) related to notification.
- `Notification.DismissButton`: The button responsible for dismissing the notification.

## Examples

### Sizes

`Notification` comes in two sizes: `medium` and `small`. By default, it uses `medium` size.

```jsx
<Flex flow="column">
  <Notification.Root size="medium">
    {'This is a medium notification.'}
  </Notification.Root>
  <Notification.Root size="small">
    {'This is a small notification.'}
  </Notification.Root>
</Flex>
```

### Types

There are four types of notifications, each with their own styles: `info`, `warning`, `error`, and `success`.
By default, a notification will be of `info` type.

`Notification` always displays an icon appropriate to its type.

<Callout variant="tip">

Place `Notification` in close proximity to whatever content area or feature it's referring to.

</Callout>

```jsx
<Flex flow="column">
  <Notification.Root type="info">
    {'This notification details some information.'}
  </Notification.Root>
  <Notification.Root type="success">
    {'This notification details some success information.'}
  </Notification.Root>
  <Notification.Root type="error">
    {'This notification details some error information.'}
  </Notification.Root>
  <Notification.Root type="warning">
    {'This notification details some warning information.'}
  </Notification.Root>
</Flex>
```

### Emphasis

`Notification` supports two emphasis styles: `subtle` (default) and `bold`. Bold emphasis notifications provide additional visual distinction in the form of a colored outline and are handy for reinforcing the severity or importance of a message.

<Callout variant="important">

Notifications should be used thoughtfully and occasionally. They are meant to highlight important information and will be [drowned out if used too frequently](https://www.nngroup.com/videos/alert-fatigue-user-interfaces/) within a single view.

</Callout>

```jsx
<Flex flow="column">
  <Notification.Root type="error" emphasis="bold">
    {'You haven’t added your address. Please provide your address to continue.'}
  </Notification.Root>
  <Notification.Root type="success" emphasis="bold">
    {'All good, you are now ready to start using our service!'}
  </Notification.Root>
</Flex>
```

### With list

Notifications can have lists of information within them, and are useful for providing error summaries when there are many errors on the page or in a long or complex form. When creating an error summary, still include inline error messaging using the [Form Field's feedback message](/components/forms/form-field#validation-status).

```jsx
<Notification.Root type="error" emphasis="bold">
  <Text as="p" marginBottom="spacingS">
    {'Make sure to provide the following fields to update your user profile:'}
  </Text>
  <Box as="ul" paddingLeft="spacingM" marginY="none">
    <Box as="li">{'Name'}</Box>
    <Box as="li">{'Email'}</Box>
    <Box as="li">{'Phone number'}</Box>
  </Box>
</Notification.Root>
```

### Action

Notification supports rendering inline, contextual action to take. You can pass a single action component as children to `Notification.Actions`.
The action content will be displayed on the end side of the notification, except when screen size is small in which case the layout will stack vertically to better accommodate all the content.

Action provides an opportunity for the user to act on the information they see in the notification or navigate them to a view or flow related to the notification itself.

<Callout variant="tip">

Be short and concise: limit content to 1 or 2 sentences when including an inline action.

</Callout>

```jsx
<Notification.Root type="error" emphasis="bold">
  {`We're having trouble connecting. Check your internet connection and try again.`}
  <Notification.Actions>
    <Button variant="outline">{'Try again'}</Button>
  </Notification.Actions>
</Notification.Root>
```

### Dismissible

`Notification` is persistent by default, but can be configured to be dismissible (unless it's critical for a user to read or interact with it) via an icon-only dismiss button.

<Callout variant="tip">

`Notification` does not dismiss automatically unlike temporary [Toaster messages](/components/toaster). It persists until the user explicitly dismisses it or takes action that resolves the notification.

</Callout>

```jsx
() => {
  const [isVisible, setIsVisible] = React.useState(true);

  return isVisible ? (
    <Notification.Root type="warning">
      {'This feature is still under development.'}
      <Notification.Actions>
        <Button variant="outline">{'View roadmap'}</Button>
      </Notification.Actions>
      <Notification.DismissButton
        label="Dismiss"
        onClick={() => setIsVisible(false)}
      />
    </Notification.Root>
  ) : (
    <Button variant="outline" onClick={() => setIsVisible(true)}>
      {'Show notification'}
    </Button>
  );
};
```

### Layout direction

`Notification` supports switching layout direction to `vertical` with `layout` property.
It can come handy when a message longer than two lines is required and/or you want to include multiple action elements.

<Callout variant="tip">

`Notification` automatically adds a standard gap between the passed action elements.

</Callout>

```jsx
<Notification.Root layout="vertical" type="info">
  {
    'This notification details a large amount information that wraps into more than two lines, forcing the height of the notification to be larger. For this kind of multi-line notifications, vertical layout with actions below the message is optimal.'
  }
  <Notification.Actions>
    <Button variant="outline">{'Action'}</Button>
    <Button variant="ghost">{'Skip for now'}</Button>
  </Notification.Actions>
</Notification.Root>
```

### Inside list

Use the `headless` prop to remove notification outline styles. This is useful in case you need to display multiple notifications in a list, for example as part of "notification center" feature.

<Callout variant="tip">

If the list is some sort of summary of notifications that already appeared, where visual impact of each entry is less important, you may want to set `variant` prop to `subtle`.

</Callout>

```jsx
<Flex as="ul" flow="column" gap="none" padding="none">
  <Box as="li">
    <Notification.Root type="warning" variant="subtle" headless addRole={false}>
      {'This is a warning notification!'}
    </Notification.Root>
    <Separator isDecorative />
  </Box>
  <Box as="li">
    <Notification.Root type="error" variant="subtle" headless addRole={false}>
      {'This is an error notification!'}
      <Notification.Actions>
        <Button variant="outline">{'Action'}</Button>
      </Notification.Actions>
    </Notification.Root>
    <Separator isDecorative />
  </Box>
  <Box as="li">
    <Notification.Root type="success" variant="subtle" headless addRole={false}>
      {'This is a success notification!'}
      <Notification.Actions>
        <Button variant="outline">{'Action'}</Button>
      </Notification.Actions>
    </Notification.Root>
  </Box>
</Flex>
```

---

## Accessibility features

`Notification` automatically assigns correct ARIA role and gets announced by screen readers when it gets rendered on the screen.

- Error and warning notifications have a `role=”alert”`. With this role the screen reader will promptly interrupt any ongoing content reading and prioritize the notification content for immediate attention.
- All other notifications have a `role=”status”`. With this role, the screen readers must finish what it started reading before the content of notification is read out.

---

## API Reference

### Notification.Root

| Name       | Type                                          | Default        | Description                                                                                                                                                                                                                                   | Required |
| ---------- | --------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css`      | `StitchesCss`                                 |                | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. |          |
| `size`     | `"medium" \| "small"`                         | `"medium"`     | The size of the notification.                                                                                                                                                                                                                 |          |
| `type`     | `"info" \| "warning" \| "error" \| "success"` | `"info"`       | Type of the notification.                                                                                                                                                                                                                     |          |
| `emphasis` | `"regular" \| "bold"`                         | `"regular"`    | Emphasis of the notification.                                                                                                                                                                                                                 |          |
| `variant`  | `"strong" \| "subtle"`                        | `strong`       | Visual variant of the notification.                                                                                                                                                                                                           |          |
| `layout`   | `"horizontal" \| "vertical"`                  | `"horizontal"` | Controls layout direction of the notification.                                                                                                                                                                                                |          |
| `headless` | `boolean`                                     | `false`        | When `true`, removes the outline styles from the notification.                                                                                                                                                                                |          |
| `addRole`  | `boolean`                                     | `true`         | When `false`, removes `role` ARIA attribute from the notification.                                                                                                                                                                            |          |

### Notification.Actions

<Callout variant="tip">

In addition to the props below, you can pass [Flex props](/components/layout/flex#api-reference) to control the layout.

</Callout>

| Name  | Type          | Default | Description                                                                                                                                                                                                                                   | Required |
| ----- | ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css` | `StitchesCss` |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. |          |

### Notification.DismissButton

| Name    | Type          | Default | Description                                                                                                                                                                                                                                   | Required |
| ------- | ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css`   | `StitchesCss` |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. |          |
| `label` | `string`      |         | The `aria-label` of the button to use for screen readers.                                                                                                                                                                                     | Yes      |