Notification Stack

A stacked notification card system with swipe-to-dismiss gestures, auto-pagination, action buttons, and animated transitions.

Edit on GitHubEditllms.txt

Client Only

Installation

pnpm dlx @docyrus/cli add @docyrus/ui-notification-stack

Required Packages(2 packages)

pnpm add motion @emotion/is-prop-valid

Usage

import {
  NotificationStack
} from '@docyrus/ui/components/notification-stack';
import type { NotificationItem } from '@docyrus/ui/components/notification-stack';

const notifications: NotificationItem[] = [
  {
    id: '1',
    type: 'success',
    title: 'Deployment complete',
    message: 'Your app has been deployed successfully.',
    actions: [{ label: 'View' }]
  },
  {
    id: '2',
    type: 'warning',
    title: 'Storage warning',
    message: 'You are using 90% of your storage quota.'
  },
  {
    id: '3',
    type: 'info',
    title: 'New feature',
    message: 'Dark mode is now available in settings.',
    variant: 'unread'
  }
];

<NotificationStack
  notifications={notifications}
  onDismiss={(id) => console.log('dismissed', id)}
  onClick={(id) => console.log('clicked', id)}
  onAction={(id, action) => console.log('action', id, action)}
/>

With Pagination & Load More

<NotificationStack
  notifications={notifications}
  maxVisible={5}
  loadMoreThreshold={2}
  onLoadMore={() => fetchMoreNotifications()}
  onDismiss={handleDismiss}
  emptyState={<p>No notifications</p>}
/>

Variants

Variant	Description
`default`	Standard notification cards.
`bordered`	Cards with enhanced shadow (`shadow-md`).

Sizes

Size	Description
`sm`	Compact padding and smaller text.
`default`	Standard sizing.
`lg`	Larger padding and text.

Components

Component	Description
`NotificationStack`	Main container. Manages stacking, pagination, and dismissed state.
`NotificationStackCard`	Individual notification card with swipe-to-dismiss gesture.

API Reference

NotificationStack

Prop	Type	Default	Description
`notifications`	`NotificationItem[]`	—	Array of notification items to display.
`maxVisible`	`number`	`10`	Maximum number of visible cards before pagination.
`loadMoreThreshold`	`number`	`2`	When remaining count reaches this threshold, `onLoadMore` is triggered.
`onLoadMore`	`() => void`	—	Called when more notifications should be fetched.
`onDismiss`	`(id: string) => void`	—	Called when a notification is swiped away.
`onClick`	`(id: string) => void`	—	Called when a notification card is clicked.
`onAction`	`(id: string, action: string) => void`	—	Called when an action button is clicked.
`variant`	`'default' \| 'bordered'`	`'default'`	Visual style.
`size`	`'sm' \| 'default' \| 'lg'`	`'default'`	Card sizing.
`emptyState`	`ReactNode`	—	Content shown when no notifications exist.
`className`	`string`	—	Additional CSS classes.

Type Reference

NotificationItem

Field	Type	Description
`id`	`string`	Unique identifier.
`type`	`'default' \| 'success' \| 'warning' \| 'error' \| 'info'`	Notification type (determines icon and color).
`title`	`string`	Notification title.
`message`	`string`	Notification body text.
`icon`	`ReactNode \| string`	Custom icon override.
`badge`	`ReactNode`	Badge content displayed alongside the notification.
`actions`	`Array<{ label: string; onClick?: () => void }>`	Action buttons displayed at the bottom.
`variant`	`'default' \| 'unread' \| 'highlighted'`	Visual variant for the individual card.

Interaction Details

Swipe to dismiss: Drag horizontally past 100px or at 500px/s velocity.
Stacking: Cards stack with scale reduction (5% per level) and vertical offset (10px per level).
Pointer events: Only the top card is interactive; stacked cards below are visual-only.
Auto-dismiss on action: Cards are dismissed after an action button click.

Notification Stack

On this page