Notification

Imperative toast-style notifications fired with notify(). Four card layouts, from a one-line strip to a centered compact card.

Playground

title

description

variant

actionType

showClose

notify({
  title: "System Update Available",
  description: "Update now to enjoy new features.",
  actionType: "single",
  actions: [{ label: "Update", onClick: () => {} }],
})

Preview

Call notify() from any event handler. The default variant is a single-row card; add a prefix icon, a close button with showClose: true, or a trailing action. A NotificationToaster must be mounted once in your app.

<Button
  variant="outline"
  onClick={() =>
    notify({
      title: "Update available. Get new features!",
      prefix: <Info />,
      showClose: true,
      actionType: "single",
      actions: [{ label: "Update", onClick: () => {} }],
    })
  }
>
  Notify
</Button>

<NotificationToaster />

Installation

npx shadcn@latest add https://espresso-base-ui.vercel.app/r/notification.json

Usage

import {
  notify,
  NotificationToaster,
  notificationVariants,
  type NotificationOptions,
  type NotificationAction,
} from "@/components/ui/notification"

// Mount the toaster once (e.g. in your root layout)
<NotificationToaster />

// Then fire notifications from anywhere
notify({
  title: "Saved",
  description: "Your changes are safe.",
})

Banner with actions

variant: "banner" stacks the title above a description. actionType: "dual" renders two side-by-side buttons below the copy; actionType: "single" renders just the first one. Buttons close the notification after running their onClick.

notify({
  variant: "banner",
  title: "Update available. Get new features!",
  description:
    "A new update is available for the app. Update now to enjoy new features and improvements.",
  prefix: <Info />,
  showClose: true,
  actionType: "dual",
  actions: [
    { label: "Update now", onClick: () => {} },
    { label: "Later", onClick: () => {} },
  ],
})

Avatar

variant: "avatar" is built for activity feeds: pass an avatar as prefix, a relative timestamp, and unread: true for a blue unread dot at the top-right corner (the close button takes that spot when both are enabled).

notify({
  variant: "avatar",
  title: "Jane Johnson",
  description: "Your task is due tomorrow",
  timestamp: "28 min ago",
  prefix: (
    <Avatar size="xl">
      <AvatarImage src="https://i.pravatar.cc/40?img=47" />
      <AvatarFallback>JJ</AvatarFallback>
    </Avatar>
  ),
  unread: true,
})

Compact

variant: "compact" centers the copy and lays the actions out full-width – one full-width button for single, side by side for dual.

notify({
  variant: "compact",
  title: "System Update Available",
  description:
    "A new update is available for the app. Update now to enjoy new features and improvements.",
  actionType: "dual",
  actions: [
    { label: "Update now", onClick: () => {} },
    { label: "Later", onClick: () => {} },
  ],
})

API reference

notify(options) queues a notification on a dedicated toast manager (independent of the standard toast Toaster) and returns the toast id. NotificationToaster renders the queue – mount it exactly once. All fields below belong to the NotificationOptions object.

notify(options: NotificationOptions)

Prop	Type	Default	Description
variant	"default" \| "banner" \| "avatar" \| "compact"	"default"	Card layout – single row, stacked banner, avatar feed item, or centered compact card.
title	string	–	Required heading text.
description	string	–	Supporting copy in muted text below (or beside) the title.
prefix	React.ReactNode	–	Leading visual – an icon (auto-sized to size-4) or an Avatar.
showClose	boolean	false	Shows a close (✕) button – inline at the row's end for default, top-right for the other layouts.
actionType	"none" \| "single" \| "dual"	"none"	How many action buttons render: none, the first one, or the first two.
actions	NotificationAction[]	[]	Buttons to render. Each closes the notification after its onClick runs.
timestamp	string	–	Small muted timestamp line (e.g. "28 min ago") – pairs with the avatar variant.
unread	boolean	–	Shows a blue unread dot at the top-right corner (avatar variant, hidden when showClose is set).
duration	number	90000	Auto-dismiss timeout in milliseconds.
position	"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"	–	Declared viewport-corner option on NotificationOptions; placement is ultimately controlled by the toaster viewport.

NotificationAction

Prop	Type	Default	Description
label	string	–	Button text.
onClick	() => void	–	Handler – the notification closes itself afterwards.
variant	Button["variant"]	–	Optional Button variant override. Defaults per layout: secondary/outline pairs for dual actions, ghost for the default row.

Styling hooks

Each card renders with data-slot="notification" and data-variant reflecting the active layout – target these from CSS for app-level overrides. Cards are rendered inside the Toast primitives, so they inherit the toast stacking and slide animations. The notificationVariants cva helper is exported for building custom cards with the same layout classes.