# NotificationCenter

> The list that opens from the bell and holds the state of the whole server — a computer offline, a quota nearly full, an update — until it changes.

Source: https://raft-design.botiverse.build/components/notification-center. Generated from the current release; where it differs from what you remember, this page is right.

The NotificationCenter is the list that opens from the bell. It holds the state of the whole server (a computer offline, a quota nearly full, an update) and keeps each notice until the situation changes. An attention dot on the bell says that something is unread.

## When to use

| Situation                                               | Use                                                               |
| ------------------------------------------------------- | ----------------------------------------------------------------- |
| A problem or a change that affects the whole server     | NotificationCenter                                                |
| Something happened elsewhere that the person should see | Activity ([ActivityInbox](https://raft-design.botiverse.build/components/activity-inbox.md))   |
| Something in one panel failed                           | `PanelNotice` under the panel header ([Panel](https://raft-design.botiverse.build/components/panel.md)) |
| The result of an action the person took                 | [Toast](https://raft-design.botiverse.build/components/toast.md)                                        |

Errors by scope are in [Feedback](https://raft-design.botiverse.build/patterns/feedback.md#errors-by-scope). Where a product puts the bell is on the product's own page.

## Anatomy

- `NotificationCenter`: the root. A non-modal popover.
- `NotificationCenterTrigger`: the bell. By default it draws the bell and the attention dot.
- `NotificationCenterPopup`: the list's popup, next to the bell.
  - `NotificationCenterHeader`: `NotificationCenterTitle` (Notifications) and `NotificationCenterCount`.
  - `NotificationCenterScroller` and `NotificationCenterList`: the notices.
  - `NotificationCenterEmptyState`: what the list says when it is empty ([EmptyState](https://raft-design.botiverse.build/components/empty-state.md)).
- `NotificationCenterItem`: one notice, in a `NotificationCenterItemRow`:
  - `NotificationCenterItemIcon`: a tile with an icon. A notice from the system has no who, so a tile stands where an avatar would ([InboxItem](https://raft-design.botiverse.build/components/inbox-item.md#rules)).
  - `NotificationCenterItemContent`: `NotificationCenterItemTitle`, `NotificationCenterItemBody` and `NotificationCenterItemActions` with `NotificationCenterActionButton`s.

## Variants

| Variant                          | Use for                                                                                                                  |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `status="error"` on the icon     | Something stopped working: a computer offline, an agent that can't start. `warning-soft` tile, `octagon-alert` icon      |
| `status="warning"`               | Something will stop working soon: a quota nearly full, a key about to expire. `warning-soft` tile, `triangle-alert` icon |
| `status="info"`                  | News: an update. `info-soft` tile, `info` icon                                                                           |
| `viewport="mobile"` on the popup | The narrower popup on a phone                                                                                            |
| `size` on the popup              | The popup's height: `sm`, `md` or `lg`                                                                                   |

## States

| State            | Look                                                                           |
| ---------------- | ------------------------------------------------------------------------------ |
| Unread (default) | The title in `foreground` at weight 700, and a pink attention dot on the right |
| `read`           | The title in `foreground-muted` at weight 600; no dot                          |

## Behavior

- Sort notices by severity: errors first, then warnings, then information.
- When the person dismisses a notice, don't show it again until the situation changes.
- Show the attention dot on the bell only while a notice is unread. The default trigger always draws the dot, so pass the bell alone as the trigger's children when nothing is unread.
- Float the popup next to the bell; it doesn't take space in the layout ([Elevation](https://raft-design.botiverse.build/foundations/elevation.md#popups)).

## Content

- Write the notice in the same order as an inbox item: where (the computer, the server), then what happened, then at most 2 lines of detail ([InboxItem](https://raft-design.botiverse.build/components/inbox-item.md#content)).

## Accessibility

- `NotificationCenter` wraps the Base UI `Popover`, non-modal by default; the popup doesn't take focus when it opens.
- The popup is named "Notification center" and the list "Notifications" unless you pass another `aria-label`.
- Give the trigger an accessible name, and include the unread state: `aria-label="Notifications, 2 unread"`. The bell and the dot are hidden from assistive technology.
- `NotificationCenterItemIcon` is an image (`role="img"`) named by its status (Error, Warning, Info).

## Rules

- Make the actions in a notice ink-outline small buttons, never pink; `NotificationCenterActionButton` does this ([InboxItem](https://raft-design.botiverse.build/components/inbox-item.md#rules)).
- Use orange tiles for errors and warnings, not red ([Color](https://raft-design.botiverse.build/foundations/color.md#soft-tints)).

## API

### NotificationCenter

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actionsRef` | `RefObject<PopoverRootActions \| null>` |  | A ref to imperative actions. - `unmount`: Manually unmounts the popover. Call this after any externally controlled closing animation finishes. - `close`: Closes the popover imperatively when called. |
| `children` | `ReactNode \| PayloadChildRenderFunction<unknown>` |  | The content of the popover. This can be a regular React node or a render function that receives the `payload` of the active trigger. |
| `defaultOpen` | `boolean` | `false` | Whether the popover is initially open. |
| `defaultTriggerId` | `string` |  | ID of the trigger that the popover is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open popover. |
| `handle` | `BasePopover.Handle<unknown>` |  | A handle to associate the popover with a trigger. If specified, allows external triggers to control the popover's open state. |
| `modal` | `boolean \| "trap-focus"` | `false` | Determines if the popover enters a modal state when open. - `true`: user interaction is limited to the popover: document page scroll is locked, and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. - `'trap-focus'`: focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled. |
| `onOpenChange` | `(open: boolean, eventDetails: BasePopover.Root.ChangeEventDetails) => void` |  | Event handler called when the popover is opened or closed. |
| `onOpenChangeComplete` | `(open: boolean) => void` |  | Event handler called after any animations complete when the popover is opened or closed. |
| `open` | `boolean` |  | Whether the popover is currently open. |
| `triggerId` | `string` |  | ID of the trigger that the popover is associated with. This is useful in conjunction with the `open` prop to create a controlled popover. There's no need to specify this prop when the popover is uncontrolled (that is, when the `open` prop is not set). |

### NotificationCenterActionButton

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `loading` | `boolean` |  |  |
| `loadingLabel` | `string` |  |  |
| `focusableWhenDisabled` | `boolean` | `false` | Whether the button should be focusable when disabled. |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### NotificationCenterCount

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### NotificationCenterEmptyState

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### NotificationCenterHeader

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### NotificationCenterItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `read` | `boolean` | `false` |  |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### NotificationCenterItemActions

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### NotificationCenterItemBody

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### NotificationCenterItemContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### NotificationCenterItemIcon

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `"warning" \| "success" \| "error" \| "info"` | `"info"` |  |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### NotificationCenterItemRow

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### NotificationCenterItemTitle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### NotificationCenterList

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### NotificationCenterPopup

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `portalProps` | `PopoverPortalProps` |  |  |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` |  |
| `viewport` | `"desktop" \| "mobile"` | `"desktop"` |  |
| `align` | `Align` | `"center"` | How to align the popup relative to the specified side. |
| `alignOffset` | `number \| OffsetFunction` | `0` | Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. |
| `anchor` | `Element \| VirtualElement \| RefObject<Element \| null> \| (() => Element \| VirtualElement \| null)` |  | An element to position the popup against. By default, the popup will be positioned against the trigger. |
| `arrowPadding` | `number` | `5` | Minimum distance to maintain between the arrow and the edges of the popup. |
| `collisionAvoidance` | `CollisionAvoidance` |  | Determines how to handle collisions when positioning the popup. |
| `collisionBoundary` | `Boundary` | `'clipping-ancestors'` | An element or a rectangle that delimits the area that the popup is confined to. |
| `collisionPadding` | `Padding` | `5` | Additional space to maintain from the edge of the collision boundary. |
| `disableAnchorTracking` | `boolean` | `false` | Whether to disable the popup from tracking any layout shift of its positioning anchor. |
| `finalFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => void \| boolean \| HTMLElement \| null)` |  | Determines the element to focus when the popover is closed. |
| `initialFocus` | `boolean \| RefObject<HTMLElement \| null> \| ((openType: InteractionType) => void \| boolean \| HTMLElement \| null)` | `false` | Determines the element to focus when the popover is opened. By default, focus moves to the first tabbable element inside the popup, except when the popover is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard. |
| `positionMethod` | `"fixed" \| "absolute"` | `"fixed"` | Determines which CSS `position` property to use. |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |
| `side` | `Side` | `"bottom"` | Which side of the anchor element to align the popup against. May automatically change to avoid collisions. |
| `sideOffset` | `number \| OffsetFunction` | `4` | Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. |
| `sticky` | `boolean` | `false` | Whether to maintain the popup in the viewport after the anchor element was scrolled out of view. |

Also takes the attributes of its element.

### NotificationCenterScroller

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### NotificationCenterTitle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

### NotificationCenterTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `closeDelay` | `number` | `0` | How long to wait before closing the popover that was opened on hover. Specified in milliseconds. |
| `delay` | `number` | `300` | How long to wait before the popover may be opened on hover. Specified in milliseconds. |
| `handle` | `BasePopover.Handle<unknown>` |  | A handle to associate the trigger with a popover. |
| `nativeButton` | `boolean` | `true` | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (e.g. `<div>`). |
| `openOnHover` | `boolean` | `false` | Whether the popover should also open when the trigger is hovered. |
| `payload` | `{}` |  | A payload to pass to the popover when it is opened. |
| `render` | `ReactElement \| ((props, state) => ReactElement)` |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |

Also takes the attributes of its element.

## Changes

- 0.7.0 (Fixed): `EmptyStateIcon` is hidden from assistive technology, and `NotificationCenterItemIcon` is announced as an image named by its status.
- 0.6.0 (Breaking Changes): **Props that no longer change anything are removed:** `Badge` `uppercase`; `Checkbox` `size`, `variant`, `color`; `Status` `pulse`, `attention` (status never animates); `Switch` / `SwitchThumb` `size`; `SidebarItem` `variant`; `SidebarItemCount` / `SidebarItemIndicator` `variant` and `appearance` (the count is always the pink sticker, the indicator the yellow @); `NotificationCenterActionButton` `variant`; `DrawerContent` `width` (one-go forms use the wide `Dialog`); `AppRailItemIndicator` `attention`; `AppRailItemAttention` `children`; `Steps` `size`, `track`, `renderIndicator`, `renderTraveler`; `FilePreviewBadge` `type`, `color`. Remove them at call sites.