Notifications

The Notifications view provides a centralized interface for managing alerts, updates, and system messages. Users can view, filter, mark as read, and manage notification preferences.

Type Signature

interface NotificationsViewProps {
  /** Page title */
  title?: string
  /** Page description */
  description?: string
  /** View layout mode */
  layout?: 'single' | 'column' | 'canvas' | 'vibe'
  /** Notifications list */
  notifications?: Array<{
    id: string
    type: string
    title: string
    message: string
    timestamp: string
    read: boolean
    icon?: string
    actionUrl?: string
  }>
  /** Filter by type */
  filter?: 'all' | 'unread' | 'read' | 'mentions' | 'updates'
  /** Group by date */
  groupByDate?: boolean
  /** Show filter controls */
  showFilters?: boolean
  /** Page-level action buttons */
  actions?: Array<{
    id: string
    label: string
    icon?: string
    onClick?: () => void
    variant?: 'default' | 'primary' | 'destructive'
  }>
  /** Loading state */
  loading?: boolean
  /** Error state */
  error?: string
  /** Child content */
  children?: React.ReactNode
}

Usage

<App name="Acme Dashboard">
  <Shell>
    <NotificationsView
      title="Notifications"
      filter="unread"
      groupByDate={true}
      showFilters={true}
      notifications={[
        {
          id: '1',
          type: 'mention',
          title: 'John mentioned you',
          message: 'John mentioned you in a comment',
          timestamp: '2024-01-15T10:30:00Z',
          read: false,
          icon: 'AtSign',
          actionUrl: '/comments/123'
        },
        {
          id: '2',
          type: 'update',
          title: 'System update',
          message: 'New features available',
          timestamp: '2024-01-14T15:00:00Z',
          read: true,
          icon: 'Bell'
        }
      ]}
    />
  </Shell>
</App>

Props

title

The page title displayed in the header. Defaults to "Notifications".

<NotificationsView title="Activity">

description

Optional page description.

<NotificationsView
  title="Notifications"
  description="Stay updated with the latest activity"
>

layout

Layout mode for the notifications content. Defaults to 'single'.

// Single column list (default)
<NotificationsView layout="single">

// Multi-column layout
<NotificationsView layout="column">

notifications

Array of notification items to display.

<NotificationsView
  notifications={[
    {
      id: 'notif_1',
      type: 'mention',
      title: 'Sarah mentioned you',
      message: 'Sarah mentioned you in "Project Alpha"',
      timestamp: '2024-01-15T10:30:00Z',
      read: false,
      icon: 'AtSign',
      actionUrl: '/projects/alpha#comment-123'
    },
    {
      id: 'notif_2',
      type: 'assignment',
      title: 'New task assigned',
      message: 'You were assigned to "Update Documentation"',
      timestamp: '2024-01-15T09:15:00Z',
      read: false,
      icon: 'CheckSquare',
      actionUrl: '/tasks/456'
    },
    {
      id: 'notif_3',
      type: 'update',
      title: 'Deployment successful',
      message: 'Production deployment completed successfully',
      timestamp: '2024-01-14T22:00:00Z',
      read: true,
      icon: 'Rocket',
      actionUrl: '/deployments/789'
    }
  ]}
/>

filter

Current filter for notifications. Defaults to 'all'.

// Show all notifications (default)
<NotificationsView filter="all">

// Show only unread
<NotificationsView filter="unread">

// Show only read
<NotificationsView filter="read">

// Show only mentions
<NotificationsView filter="mentions">

// Show only updates
<NotificationsView filter="updates">

groupByDate

Group notifications by date. Defaults to true.

// Group by date (default)
<NotificationsView groupByDate={true}>
  {/* Shows "Today", "Yesterday", "Last Week" */}
</NotificationsView>

// Flat list
<NotificationsView groupByDate={false}>
  {/* Shows all notifications in a single list */}
</NotificationsView>

showFilters

Display filter controls. Defaults to true.

// Show filters (default)
<NotificationsView showFilters={true}>

// Hide filters
<NotificationsView showFilters={false}>

actions

Page-level action buttons.

<NotificationsView
  actions={[
    {
      id: 'mark-all-read',
      label: 'Mark All Read',
      icon: 'Check',
      onClick: () => markAllAsRead()
    },
    {
      id: 'settings',
      label: 'Notification Settings',
      icon: 'Settings',
      onClick: () => navigate('/settings/notifications')
    }
  ]}
/>

Notification Types

Different types of notifications with specific icons and styling:

Mentions

User was mentioned or tagged:

{
  type: 'mention',
  title: 'John mentioned you',
  message: 'John mentioned you in a comment',
  icon: 'AtSign',
  actionUrl: '/comments/123'
}

Assignments

Task or item assigned to user:

{
  type: 'assignment',
  title: 'New task assigned',
  message: 'You were assigned to "Update Documentation"',
  icon: 'CheckSquare',
  actionUrl: '/tasks/456'
}

Updates

System or feature updates:

{
  type: 'update',
  title: 'New features available',
  message: 'Check out the latest updates to your dashboard',
  icon: 'Sparkles',
  actionUrl: '/changelog'
}

Alerts

Important alerts or warnings:

{
  type: 'alert',
  title: 'Payment failed',
  message: 'Your payment method was declined',
  icon: 'AlertCircle',
  actionUrl: '/billing'
}

Messages

Direct messages or communications:

{
  type: 'message',
  title: 'New message from Sarah',
  message: 'Hey, can we discuss the project timeline?',
  icon: 'MessageSquare',
  actionUrl: '/messages/sarah'
}

Filter Controls

Provide filter options for users:

<NotificationsView showFilters={true}>
  <NotificationFilters
    current={filter}
    onChange={setFilter}
    options={[
      { value: 'all', label: 'All', count: 15 },
      { value: 'unread', label: 'Unread', count: 5 },
      { value: 'mentions', label: 'Mentions', count: 2 },
      { value: 'updates', label: 'Updates', count: 3 }
    ]}
  />
</NotificationsView>

Date Grouping

Group notifications by relative date:

Today
├─ Sarah mentioned you - 2 hours ago
├─ New task assigned - 4 hours ago
└─ Comment on your post - 6 hours ago

Yesterday
├─ Deployment successful - Yesterday at 10:00 PM
└─ Team invitation - Yesterday at 3:30 PM

Last Week
├─ Weekly report ready - 5 days ago
└─ Account upgrade - 6 days ago

<NotificationsView groupByDate={true}>
  {groupedNotifications.map((group) => (
    <NotificationGroup
      key={group.date}
      title={group.date}
      items={group.notifications}
    />
  ))}
</NotificationsView>

Mark as Read

Handle marking notifications as read:

const handleMarkAsRead = async (id: string) => {
  await markNotificationAsRead(id)
  updateNotifications()
}

<NotificationsView
  notifications={notifications}
  onNotificationClick={handleMarkAsRead}
/>

Bulk Actions

Allow bulk operations on notifications:

const [selected, setSelected] = useState<string[]>([])

<NotificationsView
  actions={[
    {
      id: 'mark-read',
      label: 'Mark Read',
      onClick: () => markMultipleAsRead(selected),
      disabled: selected.length === 0
    },
    {
      id: 'delete',
      label: 'Delete',
      variant: 'destructive',
      onClick: () => deleteMultiple(selected),
      disabled: selected.length === 0
    }
  ]}
>
  <NotificationList
    items={notifications}
    selectable={true}
    selected={selected}
    onSelectionChange={setSelected}
  />
</NotificationsView>

Empty States

Handle no notifications gracefully:

<NotificationsView
  notifications={notifications}
>
  {notifications.length === 0 ? (
    <EmptyState
      icon="Bell"
      title="No notifications"
      description="You're all caught up!"
    />
  ) : (
    <NotificationList items={notifications} />
  )}
</NotificationsView>

Real-Time Updates

Enable live notification updates:

useEffect(() => {
  const unsubscribe = subscribeToNotifications((newNotification) => {
    setNotifications((prev) => [newNotification, ...prev])
    showToast(newNotification.title)
  })

  return unsubscribe
}, [])

<NotificationsView
  notifications={notifications}
  realtime={true}
/>

Notification Settings

Link to notification preferences:

<NotificationsView
  actions={[
    {
      id: 'settings',
      label: 'Manage Preferences',
      icon: 'Settings',
      onClick: () => navigate('/settings/notifications')
    }
  ]}
>
  <NotificationList items={notifications} />

  <NotificationPreferences
    settings={{
      email: true,
      push: true,
      mentions: true,
      updates: false
    }}
    onChange={updatePreferences}
  />
</NotificationsView>

App Type Specializations

DeveloperApp Notifications

API and technical notifications:

<NotificationsView
  notifications={[
    {
      type: 'alert',
      title: 'API rate limit warning',
      message: 'Approaching 80% of rate limit',
      icon: 'AlertTriangle'
    },
    {
      type: 'update',
      title: 'API key rotated',
      message: 'Production API key was rotated',
      icon: 'Key'
    }
  ]}
/>

AdminApp Notifications

System and user activity:

<NotificationsView
  notifications={[
    {
      type: 'alert',
      title: 'New user signup',
      message: 'jane@example.com created an account',
      icon: 'UserPlus'
    },
    {
      type: 'alert',
      title: 'Failed login attempt',
      message: 'Suspicious login from 192.168.1.1',
      icon: 'ShieldAlert'
    }
  ]}
/>

CRMApp Notifications

Sales and customer updates:

<NotificationsView
  notifications={[
    {
      type: 'update',
      title: 'Deal closed',
      message: 'Acme Corp deal marked as won',
      icon: 'DollarSign'
    },
    {
      type: 'assignment',
      title: 'New lead assigned',
      message: 'TechStart Inc assigned to you',
      icon: 'UserCheck'
    }
  ]}
/>

Responsive Behavior

Notifications adapt to screen size:

Desktop (≥1024px)

┌─────────────────────────────────────┐
│  Notifications  [All ▼] [⚙️]        │
├─────────────────────────────────────┤
│  Today                              │
│  ☐ Sarah mentioned you  2h ago      │
│  ☐ New task assigned    4h ago      │
│                                     │
│  Yesterday                          │
│  ☑ Deployment success   Yesterday   │
└─────────────────────────────────────┘

Mobile (under 1024px)

┌──────────────────────┐
│  Notifications  [⚙️]  │
├──────────────────────┤
│  [All ▼]             │
├──────────────────────┤
│  Today               │
│  ☐ Sarah mentioned   │
│     you              │
│     2h ago           │
│                      │
│  ☐ New task          │
│     assigned         │
│     4h ago           │
└──────────────────────┘

Pagination

Handle large notification lists:

<NotificationsView
  notifications={notifications.slice(0, pageSize)}
  actions={[
    {
      id: 'load-more',
      label: 'Load More',
      onClick: () => loadMore()
    }
  ]}
/>

Integration with Payload CMS

Notifications can auto-wire to Payload collections:

// Auto-fetches from Payload 'notifications' collection
<NotificationsView collection="notifications">
  <NotificationList />
</NotificationsView>

Best Practices

Show Unread Count

Display unread count in UI:

<NotificationsView
  title={`Notifications (${unreadCount})`}
  filter="unread"
/>

Group by Date

Make notifications scannable:

// Good - organized by date
<NotificationsView groupByDate={true}>

// Bad - flat list is hard to scan
<NotificationsView groupByDate={false}>

Provide Quick Actions

Allow actions without opening notifications:

<NotificationItem
  notification={notification}
  actions={[
    { label: 'Mark Read', onClick: () => {} },
    { label: 'Delete', onClick: () => {} }
  ]}
/>

Auto-Mark as Read

Mark notifications as read when viewed:

const handleNotificationClick = (id: string) => {
  markAsRead(id)
  navigateToAction(id)
}

Accessibility

Notifications implement accessibility features:

Semantic HTML - Use <article> for notifications
ARIA live regions - Announce new notifications
Keyboard navigation - Navigate with arrow keys
Focus management - Focus on first unread

<NotificationsView
  aria-label="Notifications center"
  role="feed"
>
  <div aria-live="polite" aria-atomic="true">
    {unreadCount > 0 && (
      <span className="sr-only">
        You have {unreadCount} unread notifications
      </span>
    )}
  </div>

  {notifications.map((notification) => (
    <article
      key={notification.id}
      aria-labelledby={`notification-title-${notification.id}`}
      tabIndex={0}
    >
      <h3 id={`notification-title-${notification.id}`}>
        {notification.title}
      </h3>
      <p>{notification.message}</p>
    </article>
  ))}
</NotificationsView>

Dashboard - Dashboard view
Profile - Profile view
Settings - Settings view
Shell - App shell layout

Notifications

On this page