Push Components | Sylphx Documentation

PushPrompt

Permission prompt for push notifications with customizable messaging

NotificationBell

Bell icon with unread count badge and dropdown

NotificationList

List of notifications with actions and grouping

Quick Start

All push components are available from the SDK. Wrap your app with SylphxProvider for automatic push notification context.

Installation

import {
  PushPrompt,
  NotificationBell,
  NotificationList,
} from '@sylphx/platform-sdk/react'

PushPrompt

A customizable permission prompt that asks users to enable push notifications. Handles browser permission state automatically and provides callbacks for all user actions.

Accessible

Themeable

Basic Usage

import { PushPrompt } from '@sylphx/platform-sdk/react'

export default function App() {
  return (
    <PushPrompt
      onAllow={() => {
        console.log('User allowed notifications')
      }}
      onDeny={() => {
        console.log('User denied notifications')
      }}
      onDismiss={() => {
        console.log('User dismissed the prompt')
      }}
    />
  )
}

Props

Property	Type	Description
`onAllow`	`() => void`	Callback fired when user allows notifications
`onDeny`	`() => void`	Callback fired when user denies notifications
`onDismiss`	`() => void`	Callback fired when user dismisses the prompt
`onError`	`(error: Error) => void`	Callback fired on permission request error
`title`	`string`= "Enable Notifications"	Prompt title text
`description`	`string`= "Stay updated with important alerts"	Prompt description text
`allowLabel`	`string`= "Enable"	Allow button label
`denyLabel`	`string`= "Not now"	Deny button label
`icon`	`ReactNode`	Custom icon to display
`showDenyButton`	`boolean`= true	Show the deny button
`showCloseButton`	`boolean`= true	Show close button to dismiss
`position`	`"top" \| "bottom" \| "center"`= "bottom"	Prompt position on screen
`variant`	`"banner" \| "modal" \| "inline"`= "banner"	Visual style variant
`delay`	`number`= 3000	Delay before showing (ms)
`hideWhenGranted`	`boolean`= true	Auto-hide when permission granted
`hideWhenDenied`	`boolean`= true	Auto-hide when permission denied
`persistDismissal`	`boolean`= true	Remember dismissal in localStorage
`dismissalDays`	`number`= 7	Days to remember dismissal
`theme`	`ThemeVariables`	Custom theme overrides
`className`	`string`	Additional CSS classes

Advanced Examples

<PushPrompt
  title="Never miss an update"
  description="Get notified when your order ships, when prices drop, or when new products arrive."
  allowLabel="Yes, notify me"
  denyLabel="Maybe later"
  icon={<BellRing className="w-8 h-8 text-primary" />}
/>

Permission States

The prompt automatically handles browser permission states. It won't show if notifications are already granted or if the browser has previously denied permission.

NotificationBell

A bell icon component with an unread notification count badge. Clicking opens a dropdown or navigates to a notifications page. Perfect for headers and navigation bars.

Live Count

Dropdown

Basic Usage

import { NotificationBell } from '@sylphx/platform-sdk/react'

export function Header() {
  return (
    <header className="flex items-center justify-between p-4">
      <Logo />
      <nav className="flex items-center gap-4">
        <NotificationBell
          onClick={() => {
            console.log('Bell clicked')
          }}
        />
        <UserMenu />
      </nav>
    </header>
  )
}

Props

Property	Type	Description
`count`	`number`	Number of unread notifications (auto-fetched if not provided)
`maxCount`	`number`= 99	Max count to display before showing +
`onClick`	`() => void`	Callback when bell is clicked
`href`	`string`	Link to notifications page (alternative to onClick)
`showDropdown`	`boolean`= false	Show dropdown on click
`dropdownWidth`	`number`= 320	Dropdown width in pixels
`dropdownMaxHeight`	`number`= 400	Dropdown max height in pixels
`showBadge`	`boolean`= true	Show the count badge
`badgePosition`	`"top-right" \| "top-left"`= "top-right"	Badge position
`animated`	`boolean`= true	Animate bell on new notifications
`pulseOnNew`	`boolean`= true	Pulse animation for new notifications
`size`	`"sm" \| "md" \| "lg"`= "md"	Bell icon size
`icon`	`ReactNode`	Custom bell icon
`emptyIcon`	`ReactNode`	Icon when no notifications
`pollInterval`	`number`= 30000	Interval to poll for new notifications (ms)
`onNewNotification`	`(notification: Notification) => void`	Callback when new notification arrives
`theme`	`ThemeVariables`	Custom theme overrides
`className`	`string`	Additional CSS classes

Advanced Examples

<NotificationBell
  showDropdown={true}
  dropdownWidth={360}
  dropdownMaxHeight={500}
  onNewNotification={(notification) => {
    // Play sound or show toast
    playNotificationSound()
  }}
/>

Real-time Updates

For instant notification updates, connect to WebSocket or use Server-Sent Events. The pollInterval prop is a fallback for simpler setups.

NotificationList

A full-featured notification list with support for actions, grouping, filtering, and bulk operations. Use in a dedicated notifications page or as dropdown content.

Mark as Read

Delete

Actions

Basic Usage

import { NotificationList } from '@sylphx/platform-sdk/react'

export default function NotificationsPage() {
  return (
    <div className="max-w-2xl mx-auto py-8">
      <h1 className="text-2xl font-bold mb-6">Notifications</h1>
      <NotificationList
        onNotificationClick={(notification) => {
          // Navigate to related content
          if (notification.data?.url) {
            router.push(notification.data.url)
          }
        }}
        onMarkAsRead={(id) => {
          console.log('Marked as read:', id)
        }}
        onDelete={(id) => {
          console.log('Deleted:', id)
        }}
      />
    </div>
  )
}

Props

Property	Type	Description
`notifications`	`Notification[]`	Array of notifications (auto-fetched if not provided)
`onNotificationClick`	`(notification: Notification) => void`	Callback when a notification is clicked
`onMarkAsRead`	`(id: string) => void`	Callback when marking a notification as read
`onMarkAllAsRead`	`() => void`	Callback when marking all as read
`onDelete`	`(id: string) => void`	Callback when deleting a notification
`onDeleteAll`	`() => void`	Callback when deleting all notifications
`onAction`	`(notification: Notification, action: string) => void`	Callback for custom notification actions
`showMarkAllAsRead`	`boolean`= true	Show "Mark all as read" button
`showDeleteAll`	`boolean`= false	Show "Delete all" button
`showFilters`	`boolean`= true	Show filter tabs (all/unread)
`showGrouping`	`boolean`= true	Group notifications by date
`showTimestamps`	`boolean`= true	Show relative timestamps
`showActions`	`boolean`= true	Show action buttons on notifications
`emptyState`	`ReactNode`	Custom empty state content
`emptyStateTitle`	`string`= "No notifications"	Empty state title
`emptyStateDescription`	`string`= "You're all caught up!"	Empty state description
`loadingState`	`ReactNode`	Custom loading state
`pageSize`	`number`= 20	Number of notifications per page
`infiniteScroll`	`boolean`= true	Enable infinite scroll loading
`variant`	`"default" \| "compact" \| "detailed"`= "default"	Visual density variant
`theme`	`ThemeVariables`	Custom theme overrides
`className`	`string`	Additional CSS classes

Notification Object

Property	Type	Description
`id`required	`string`	Unique notification ID
`title`required	`string`	Notification title
`body`required	`string`	Notification body text
`icon`	`string`	Icon URL or component name
`image`	`string`	Large image URL
`read`	`boolean`= false	Whether notification has been read
`createdAt`required	`Date`	When the notification was created
`category`	`string`	Notification category for grouping
`actions`	`NotificationAction[]`	Available actions for this notification
`data`	`Record<string, unknown>`	Custom data attached to notification

Advanced Examples

<NotificationList
  showMarkAllAsRead={true}
  showDeleteAll={true}
  showFilters={true}
  showGrouping={true}
  infiniteScroll={true}
  pageSize={25}
  onNotificationClick={(notification) => {
    // Mark as read and navigate
    markAsRead(notification.id)
    if (notification.data?.url) {
      router.push(notification.data.url)
    }
  }}
  onAction={(notification, action) => {
    switch (action) {
      case 'view-order':
        router.push(`/orders/${notification.data.orderId}`)
        break
      case 'dismiss':
        deleteNotification(notification.id)
        break
    }
  }}
/>

Performance

For large notification lists, enable infiniteScroll and set an appropriate pageSize to avoid loading all notifications at once.

Theming

All push components support theming via the theme prop. Customize colors, fonts, and border radius to match your brand.

Custom Theme

import { NotificationBell, NotificationList, defaultTheme, type ThemeVariables } from '@sylphx/platform-sdk/react'

const customTheme: ThemeVariables = {
  ...defaultTheme,
  colorPrimary: '#8b5cf6',
  colorPrimaryHover: '#7c3aed',
  colorBackground: '#ffffff',
  colorForeground: '#1f2937',
  colorMuted: '#f3f4f6',
  colorMutedForeground: '#6b7280',
  colorBorder: '#e5e7eb',
  colorBadge: '#ef4444',
  colorBadgeForeground: '#ffffff',
  fontFamily: 'Inter, sans-serif',
  fontSize: '14px',
  borderRadius: '0.75rem',
}

<NotificationBell theme={customTheme} />
<NotificationList theme={customTheme} />

Property	Type	Description
`colorPrimary`	`string`= #000000	Primary brand color
`colorPrimaryHover`	`string`= #1f2937	Primary color on hover
`colorBackground`	`string`= #ffffff	Component background
`colorForeground`	`string`= #1f2937	Primary text color
`colorMuted`	`string`= #f3f4f6	Muted background
`colorMutedForeground`	`string`= #6b7280	Secondary text color
`colorBorder`	`string`= #e5e7eb	Border color
`colorBadge`	`string`= #ef4444	Badge background color
`colorBadgeForeground`	`string`= #ffffff	Badge text color
`fontFamily`	`string`= system-ui	Font family
`borderRadius`	`string`= 0.5rem	Border radius

Best Practices

Ask at the Right Time

Don't show the push prompt immediately. Wait for users to engage with your app first.

Explain the Value

Clearly communicate what notifications users will receive and why they're valuable.

Respect Dismissal

Use persistDismissal to avoid repeatedly asking users who have declined.

Keep Notifications Actionable

Include clear actions in notifications so users know what to do next.

Need more customization?

Use the push notification hooks for fully custom UI while keeping all the functionality.

Push Overview Consent Management

Push Notifications

Learn about server-side push APIs

Consent Management

GDPR-compliant consent handling