Realtime Hooks

Hooks for WebSocket-based realtime data with automatic connection management.

---

useRealtimeChannel

Subscribe to a specific WebSocket channel/topic.

Signature

function useRealtimeChannel<T = unknown>(
  options: UseRealtimeOptions & { channel: string }
): UseRealtimeChannelResult<T>

Options

Property	Type	Default	Description
path	string	Required	WebSocket endpoint path (e.g., /ws/app/realtime)
channel	string	Required	Channel name to subscribe to
debug	boolean	false	Enable debug logging
reconnectAttempts	number	5	Maximum reconnection attempts
reconnectInterval	number	3000	Interval between reconnection attempts (ms)

Return Type

Property	Type	Description
isConnected	boolean	Current connection state
lastMessage	RealtimeMessage<T> | null	Most recent message received
send	(message: object) => void	Send a message to the server
reconnect	() => void	Force reconnection

RealtimeMessage<T>

interface RealtimeMessage<T = unknown> {
  type: string
  channel?: string
  data: T
  timestamp?: string
}

---

useRealtimeConnection

Low-level hook for WebSocket connection management.

Signature

function useRealtimeConnection(
  options: UseRealtimeOptions
): UseRealtimeConnectionResult

Options

Property	Type	Default	Description
path	string	Required	WebSocket endpoint path
debug	boolean	false	Enable debug logging
reconnectAttempts	number	5	Maximum reconnection attempts
reconnectInterval	number	3000	Interval between reconnections (ms)

Return Type

Property	Type	Description
isConnected	boolean	Connection state
send	(message: object) => void	Send message
reconnect	() => void	Force reconnect
manager	WebSocketManager	Underlying manager instance

---

useRealtimeMode

Global realtime mode configuration (persisted to localStorage).

Signature

function useRealtimeMode(): RealtimeModeState

Return Type

Property	Type	Description
mode	'websocket' | 'polling'	Current mode
setMode	(mode: RealtimeMode) => void	Set mode

RealtimeMode

type RealtimeMode = 'websocket' | 'polling'

---

useRealtimeCounter

Higher-level hook for realtime counter values with trend tracking.

Signature

function useRealtimeCounter(
  options: UseRealtimeCounterOptions
): UseRealtimeCounterResult

Options

Property	Type	Default	Description
path	string	Required	WebSocket endpoint path
channel	string	Required	Channel name
countField	string	'count'	Field in message data containing the count
debug	boolean	false	Enable debug logging

Return Type

Property	Type	Description
count	number | null	Current count value
previousCount	number | null	Previous count value
trend	'up' | 'down' | 'stable'	Trend direction
isConnected	boolean	Connection state
refetch	() => void	Force reconnection

---

useRealtimeList

Higher-level hook for realtime lists with new-item highlighting.

Signature

function useRealtimeList<T>(
  options: UseRealtimeListOptions<T>
): UseRealtimeListResult<T>

Options

Property	Type	Default	Description
path	string	Required	WebSocket endpoint path
channel	string	Required	Channel name
maxItems	number	20	Maximum items to keep in list
extractItem	(msg: RealtimeMessage) => T | null	msg.data as T	Extract item from message
getItemId	(item: T) => string	item.id	Get unique ID from item
debug	boolean	false	Enable debug logging

Return Type

Property	Type	Description
items	T[]	Current list of items
newItemIds	Set<string>	IDs of newly added items (for highlighting)
isConnected	boolean	Connection state
refetch	() => void	Force reconnection

---

useRealtimeMessages

Subscribe to all messages from a WebSocket endpoint (no channel filtering).

Signature

function useRealtimeMessages<T = unknown>(
  options: UseRealtimeOptions
): UseRealtimeMessagesResult<T>

Return Type

Property	Type	Description
isConnected	boolean	Connection state
lastMessage	RealtimeMessage<T> | null	Most recent message
send	(message: object) => void	Send message
reconnect	() => void	Force reconnection

---

useRealtimeWithFallback

Utility hook for automatic mode switching between polling and WebSocket.

Signature

function useRealtimeWithFallback<TPolling, TWebSocket>(
  pollingHook: () => TPolling,
  websocketHook: () => TWebSocket,
  options?: { forceMode?: RealtimeMode }
): (TPolling | TWebSocket) & { mode: RealtimeMode }

Parameters

Parameter	Type	Description
pollingHook	() => TPolling	Hook that returns polling data
websocketHook	() => TWebSocket	Hook that returns WebSocket data
options.forceMode	RealtimeMode	Override global mode

---

WebSocketManager

Singleton manager for WebSocket connections.

Static Methods

// Get or create a manager instance for a URL
static getInstance(config: WebSocketManagerConfig): WebSocketManager

// Get existing manager by URL
static getInstanceByUrl(url: string): WebSocketManager | undefined

Instance Methods

Method	Signature	Description
subscribe	(listener: MessageListener) => () => void	Subscribe to all messages
subscribeToChannel	(channel: string, listener) => () => void	Subscribe to a channel
subscribeToConnection	(listener: ConnectionListener) => () => void	Subscribe to connection state
subscribeToErrors	(listener: ErrorListener) => () => void	Subscribe to errors
send	(message: object) => void	Send a message
reconnect	() => void	Force reconnection
getConnectionState	() => boolean	Get connection state
getUrl	() => string	Get WebSocket URL

buildWebSocketUrl

function buildWebSocketUrl(path: string): string
// Builds full WebSocket URL: ws://host/path or wss://host/path

---

See also

• useRealtime (Conceptual)
• Realtime Data Pattern
• Realtime Components