Notification

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

This Pattern is part of Siteplane UI Pro, and its source comes with a Pro license. Its previews are free to view and try.

Installation

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

Usage

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

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, 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.

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.

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.

A new photo was shared

Sofia Nguyen added a photo to the Team offsite album.

LaterView album

Pro

This example installs with a Siteplane UI Pro license key.

Get a license on the Pro page.

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.

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.

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 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.

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

API reference

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 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.