# Notification

Tell people about an update with an icon, text and actions.

Update notification with two actions

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/notification-demo
```

This Pattern is part of [Siteplane UI Pro](/pricing), and its source comes with a [Pro license](/docs/license/#patterns). Its previews are free to view and try.

## Installation

**Pro** — Installs with a Siteplane UI Pro license key. Complete the one-time [Pro setup](/docs/installation/#siteplane-ui-pro) first. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/notification
```

With npm: `npx shadcn@4.18.0 add @siteplane-pro/notification`.

## Usage

```tsx
import { Button } from "@/siteplane/components/button";
import { Notification } from "@/siteplane/components/notification";

<Notification
  actions={
    <>
      <Button profile="inline" profileTone="muted" variant="link">
        Later
      </Button>
      <Button profile="inline" variant="link">
        Install now
      </Button>
    </>
  }
  description="The new dashboard is here. Pages and exports now load faster."
  title="A new update is available"
/>;
```

## Composition

```text
Notification
├── NotificationBody
│   ├── image, avatar or icon (FeaturedIcon for a tone)
│   └── title, timestamp, description, progress and actions
└── dismiss button (when onDismiss is set)

NotificationList
└── Notification (one list item each)

notify() → toast
└── NotificationBody
```

The surface, shadow and dismiss button belong to [Toast](/docs/components/toast/), so an inline Notification previews the toast that `notify` shows. To set a notification into content instead, such as a text message shown inside a sign-in card, use `surface="raised"`: it keeps the toast's fill and radius and draws a Card's one edge instead of the floating shadow.

## Tones

Without a tone the notification shows a plain icon. Set `tone` to `neutral`, `accent`, `error`, `warning` or `success` for a featured icon: the tone's glyph with rings in the tone color. State the outcome in the title as well; color never carries it alone. The rings exist only as the pulse: they keep traveling outward from the glyph as they fade, a new ring every 2 s. Every featured icon pulses, in a `NotificationList` and a toast stack too. With `pulse={false}` or reduced motion the glyph stands alone in its 36 px box. To stop the pulse after a few waves, set `--motion-ring-pulse-count` to a number; after the last wave the glyph stands alone.

Notification tones

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/notification-tones-example
```

## Progress

Set `progress` from 0 to 100 to show an upload-style notification with a bar under the text. `progressLabel` is shown under the bar and names it for assistive technology; it defaults to the percentage. Your application updates the value while the work advances.

Upload progress notification

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/notification-progress-example
```

## Image

Set `image` to show a photo beside the text. On a narrow screen it sits above the text instead. Pass an empty `alt` when the photo only repeats the text.

Notification with a photo

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/notification-image-example
```

## Avatar

Set `avatar` for a message from a person. `status` adds a presence dot, and `timestamp` shows when the message arrived next to the title.

Message notification with a presence dot

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/notification-avatar-example
```

## Stacked notifications

Place inline notifications in a `NotificationList` to stack them with 12 px between them. An avatar, a featured icon and a plain icon lead in one 36 px column, so the titles of a list start at the same place. A notification that is added expands and fades in, and a dismissed one fades out and collapses while the others glide into place. When a notification changes its title, its tone or its lead (progress, image, avatar or icon), such as an invitation that is accepted, its content fades through to the new state in the same place. Give every notification a stable `key`.

Stacked notifications that resolve and dismiss

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/notification-list-example
```

## Toast

Call `notify` to show the same content as a toast. It needs one `ToastProvider` near the application root, and it returns the toast id, so an action can close the toast with `toastManager.close(id)`. `ToastProvider` and `toastManager` come from `@/siteplane/components/toast`, which installs with the Notification; [Toast](/docs/components/toast/) describes them. The toast has its own dismiss button. It disappears after the `timeout` you pass to `notify`, or else after the timeout of the `ToastProvider`; a `timeout` of `0` keeps it until it is dismissed.

Notification shown as a toast

**Pro** — This example installs with a Siteplane UI Pro license key. Get a license on the [Pro page](/pricing).

```bash
pnpm dlx shadcn@4.18.0 add @siteplane-pro/notification-toast-example
```

## API reference

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| Notification.title | string | required | Headline. A toast announces it to assistive technology. |
| Notification.description | ReactNode | unset | Supporting text below the title. |
| Notification.tone | neutral \| accent \| error \| warning \| success | unset | Unset shows a plain icon; a tone shows a featured icon in the tone color. The earlier names default, gray and brand still work as deprecated aliases of no tone, neutral and accent. |
| Notification.pulse | boolean | true | Keeps the rings of a tone's featured icon traveling outward from the glyph as they fade, a new ring every 2 s, in a NotificationList and a toast stack too. With false or reduced motion the featured icon shows only its glyph. |
| Notification.image | { src: string; alt: string } | unset | Photo beside the text, above it on a narrow screen. Replaces the icon and the avatar. |
| Notification.avatar | { src?: string; initials: string; alt: string; status?: AvatarStatus; statusLabel?: string } | unset | Person's avatar with an optional presence dot: online, away, busy or offline. Replaces the icon. |
| Notification.timestamp | string | unset | Time shown next to the title. |
| Notification.progress | number | unset | 0 to 100, clamped. Shows an upload icon and a progress bar. |
| Notification.progressLabel | string | `${progress}%` | Text under the bar. It also names the bar; without it the name is the title. |
| Notification.actions | ReactNode | unset | Inline link Buttons: variant link and profile inline, with profileTone muted for the secondary action. |
| Notification.onDismiss | () => void | unset | Shows the dismiss button and runs when it is pressed. Notification only. |
| Notification.dismissLabel | string | Dismiss {title} | Accessible name of the dismiss button. Notification only. |
| Notification.surface | floating \| raised | floating | floating is the toast's surface with its floating shadow. raised sets the notification into content with a Card's edge and no floating shadow. Notification only. |
| Notification.className | string | unset | Classes for the surface. Notification only. |
| NotificationBody | NotificationProps | — | The content without the surface and the dismiss button. notify places it in a toast. |
| NotificationList | NotificationListProps | — | Stacks inline notifications with 12 px between them and animates the ones that are added, dismissed or resolved. Every child is one Notification with a stable key. |
| NotificationList.aria-label | string | Notifications | Accessible name of the list. Replace it with a name that fits the stack. |
| notify(props, options) | (props, { timeout?: number; manager?: ToastManager }) => string | the ToastProvider's timeout; toastManager | Shows the notification as a toast and returns its id. props are the Notification props without onDismiss and className; timeout is in milliseconds. Pass manager when the ToastProvider has a toastManager of its own. |
| FeaturedIcon.icon | ComponentType<SVGProps<SVGSVGElement>> | required | Icon drawn at 18 px. |
| FeaturedIcon.tone | neutral \| accent \| error \| warning \| success | required | Color of the glyph and its rings. gray and brand still work as deprecated aliases of neutral and accent. |
| FeaturedIcon.pulse | boolean | true | Keeps the rings traveling outward from the glyph as they fade, a new ring every 2 s. With false or reduced motion the icon shows only its glyph. |
| FeaturedIcon.className | string | unset | Classes for the 36 px box. |
Each tone draws a fixed glyph: neutral an info mark, accent and error an
exclamation mark, warning a triangle and success a check. Exported types:
`NotificationProps`, `NotificationListProps`, `NotificationSurface`,
`NotificationTone` and `FeaturedIconTone`, with `NotificationDeprecatedTone` and
`FeaturedIconDeprecatedTone` for the earlier names. `Notification` and
`NotificationBody` share the content props; the surface with its `surface` prop,
`onDismiss`, `dismissLabel` and `className` belong to `Notification` alone.
`NotificationListProps` are the native ul props.

## Usage notes

Notification only presents a message. Your application decides when it appears and owns its queue, persistence and read state. It carries no live-region semantics inline; a toast is announced by Toast, which reads the `title`, so keep the title short and state the result in it.

Actions are ordinary Buttons and do not close a toast on their own. Close it from the handler with `toastManager.close(id)`, and use real destinations for links. Keep an error that blocks a task beside the field or in an [alert dialog](/docs/components/alert-dialog/) instead of a notification that disappears.

In a `NotificationList`, pass each notification as a direct child with a stable `key`: an index as the key makes a dismissed notification leave as its neighbor, and a fragment around several notifications counts as one. A leaving notification is inert, so move focus before you remove one that holds it. With reduced motion, from the system setting or `SiteplaneMotionProvider preset="reduced"`, every change is instant.