@lilith/ui-realtime

Real-time indicator components for live status, notifications, presence, and activity displays.

Features

• NotificationCenter - notification panel with grouping and actions
• NotificationBell - bell icon with unread count
• LiveIndicator - pulsing live/online indicator
• ActivityIndicator - activity status with custom states
• PresenceAvatar - avatar with presence status overlay
• TypingIndicator - animated typing dots
• RealtimeCounter - live updating counter

Installation

pnpm add @lilith/ui-realtime

Peer Dependencies

{
  "react": "^18.0.0",
  "react-dom": "^18.0.0",
  "styled-components": "^6.0.0"
}

Usage

NotificationCenter

Full notification panel:

import { NotificationCenter, type Notification } from '@lilith/ui-realtime';

const notifications: Notification[] = [
  {
    id: '1',
    type: 'message',
    title: 'New Message',
    message: 'Jane sent you a message',
    timestamp: new Date(),
    read: false,
    avatar: 'https://example.com/jane.jpg',
  },
  {
    id: '2',
    type: 'system',
    title: 'Payment Received',
    message: 'You received $50.00',
    timestamp: new Date(Date.now() - 3600000),
    read: true,
  },
];

<NotificationCenter
  notifications={notifications}
  onNotificationClick={(notification) => handleClick(notification)}
  onMarkAsRead={(id) => markAsRead(id)}
  onMarkAllAsRead={() => markAllAsRead()}
  onClear={() => clearNotifications()}
/>

With custom rendering:

<NotificationCenter
  notifications={notifications}
  renderNotification={(notification) => (
    <CustomNotificationItem notification={notification} />
  )}
/>

NotificationBell

Bell icon with unread count:

import { NotificationBell } from '@lilith/ui-realtime';

<NotificationBell
  count={5}
  onClick={() => toggleNotificationPanel()}
/>

// Animated when new notification arrives
<NotificationBell
  count={unreadCount}
  animate={hasNewNotification}
  onClick={() => toggleNotificationPanel()}
/>

// Hide count when zero
<NotificationBell count={0} hideZero />

LiveIndicator

Pulsing live status indicator:

import { LiveIndicator } from '@lilith/ui-realtime';

// Basic usage
<LiveIndicator isLive={true} />

// With label
<LiveIndicator isLive={true} label="LIVE" />

// Custom colors
<LiveIndicator isLive={true} color="#ef4444" />

// Sizes
<LiveIndicator isLive={true} size="sm" />
<LiveIndicator isLive={true} size="md" />
<LiveIndicator isLive={true} size="lg" />

ActivityIndicator

Show activity status:

import { ActivityIndicator } from '@lilith/ui-realtime';

// Status variants
<ActivityIndicator status="active" label="Active now" />
<ActivityIndicator status="idle" label="Away" />
<ActivityIndicator status="offline" label="Offline" />

// Custom activity
<ActivityIndicator status="streaming" label="Streaming" />
<ActivityIndicator status="recording" label="Recording" />

PresenceAvatar

Avatar with presence overlay:

import { PresenceAvatar } from '@lilith/ui-realtime';

<PresenceAvatar
  src="https://example.com/avatar.jpg"
  alt="Jane Doe"
  status="online"
/>

// Status options
<PresenceAvatar src={avatarUrl} status="online" />
<PresenceAvatar src={avatarUrl} status="away" />
<PresenceAvatar src={avatarUrl} status="busy" />
<PresenceAvatar src={avatarUrl} status="offline" />
<PresenceAvatar src={avatarUrl} status="invisible" />

// With size variants
<PresenceAvatar src={avatarUrl} status="online" size="sm" />
<PresenceAvatar src={avatarUrl} status="online" size="md" />
<PresenceAvatar src={avatarUrl} status="online" size="lg" />

// Show status text on hover
<PresenceAvatar src={avatarUrl} status="away" showTooltip />

TypingIndicator

Animated typing indicator:

import { TypingIndicator } from '@lilith/ui-realtime';

// Basic
<TypingIndicator />

// With names
<TypingIndicator names={['Jane']} />
<TypingIndicator names={['Jane', 'John']} />
<TypingIndicator names={['Jane', 'John', 'Alice']} />

// Custom text
<TypingIndicator names={['Jane']} suffix="is writing..." />

RealtimeCounter

Live updating counter:

import { RealtimeCounter } from '@lilith/ui-realtime';

<RealtimeCounter
  value={viewerCount}
  label="viewers"
  animate={true}
/>

// With formatting
<RealtimeCounter
  value={1234567}
  label="total views"
  format="compact" // Shows "1.2M"
/>

// Highlight changes
<RealtimeCounter
  value={subscriberCount}
  label="subscribers"
  highlightOnChange={true}
/>

// With icon
<RealtimeCounter
  value={likes}
  icon={<HeartIcon />}
/>

API Reference

NotificationCenterProps

Prop	Type	Default	Description
notifications	Notification[]	[]	Notifications array
onNotificationClick	(notification) => void	-	Click handler
onMarkAsRead	(id: string) => void	-	Mark as read handler
onMarkAllAsRead	() => void	-	Mark all as read
onClear	() => void	-	Clear all handler
renderNotification	(notification) => ReactNode	-	Custom renderer
emptyMessage	string	'No notifications'	Empty state message

Notification

interface Notification {
  id: string;
  type: 'message' | 'system' | 'alert' | 'success' | 'warning' | 'error';
  title: string;
  message: string;
  timestamp: Date;
  read: boolean;
  avatar?: string;
  action?: {
    label: string;
    onClick: () => void;
  };
  metadata?: Record<string, any>;
}

NotificationBellProps

Prop	Type	Default	Description
count	number	0	Unread count
onClick	() => void	-	Click handler
animate	boolean	false	Animate on new
hideZero	boolean	false	Hide badge when 0
maxCount	number	99	Max count to display

LiveIndicatorProps

Prop	Type	Default	Description
isLive	boolean	required	Live status
label	string	-	Optional label
color	string	'#ef4444'	Indicator color
size	'sm' | 'md' | 'lg'	'md'	Indicator size

ActivityIndicatorProps

Prop	Type	Default	Description
status	'active' | 'idle' | 'offline' | string	required	Activity status
label	string	-	Status label

PresenceAvatarProps

Prop	Type	Default	Description
src	string	-	Avatar URL
alt	string	-	Alt text
status	'online' | 'away' | 'busy' | 'offline' | 'invisible'	required	Presence status
size	'sm' | 'md' | 'lg'	'md'	Avatar size
showTooltip	boolean	false	Show status tooltip

TypingIndicatorProps

Prop	Type	Default	Description
names	string[]	[]	Names of people typing
suffix	string	'is typing...'	Text after names

RealtimeCounterProps

Prop	Type	Default	Description
value	number	required	Counter value
label	string	-	Counter label
icon	ReactNode	-	Optional icon
animate	boolean	true	Animate changes
format	'number' | 'compact'	'number'	Number format
highlightOnChange	boolean	false	Highlight on change

Types

import type {
  NotificationCenterProps,
  Notification,
  NotificationBellProps,
  LiveIndicatorProps,
  ActivityIndicatorProps,
  PresenceAvatarProps,
  TypingIndicatorProps,
  RealtimeCounterProps,
} from '@lilith/ui-realtime';

License

MIT