Realtime Components

Overview

Katalyst provides components for displaying realtime data and connection status:

• ConnectionStatus — Shows live/disconnected indicator
• LiveCounter — Animated counter for realtime metrics
• RealtimeDevSettings — Developer settings for mode switching

These components are designed to work with Katalyst's realtime primitives.

---

ConnectionStatus

Purpose

Displays the current realtime connection status with a pulsing indicator.

Basic usage

import { ConnectionStatus } from '@/shared/ui/components/realtime'
import { useRealtimeChannel } from '@/shared/infrastructure/realtime'

export function Header() {
  const { isConnected } = useRealtimeChannel({
    path: '/ws/app/realtime',
    channel: 'status',
  })

  return (
    <header>
      <ConnectionStatus
        isConnected={isConnected}
        mode="websocket"
        showLabel
      />
    </header>
  )
}

Props

Prop	Type	Default	Description
isConnected	boolean	Required	Connection state
mode	'websocket' | 'polling'	'websocket'	Connection mode
showMode	boolean	true	Show WS/Poll indicator
showLabel	boolean	true	Show text label
labels	{ connected?, connecting?, disconnected? }	Default labels	Custom labels
size	'sm' | 'md' | 'lg'	'md'	Size variant
className	string	-	Additional class

Visual states

• Connected: Green pulsing dot with "Live" label
• Connecting/Disconnected: Yellow static dot with status label

---

LiveCounter

Purpose

Displays an animated counter that smoothly transitions between values, ideal for realtime metrics.

Basic usage

import { LiveCounter } from '@/shared/ui/components/realtime'
import { useRealtimeCounter } from '@/shared/infrastructure/realtime'

export function ActiveUsersWidget() {
  const { count, previousCount, trend } = useRealtimeCounter({
    path: '/ws/metrics/realtime',
    channel: 'active-users',
  })

  return (
    <LiveCounter
      value={count}
      previousValue={previousCount}
      trend={trend}
      suffix=" users"
    />
  )
}

Props

Prop	Type	Default	Description
value	number | null	Required	Current value
previousValue	number | null	-	Start value for animation
trend	'up' | 'down' | 'stable'	'stable'	Trend direction
duration	number	1	Animation duration (seconds)
decimals	number	0	Decimal places
prefix	string	''	Text before number
suffix	string	''	Text after number
separator	string	','	Thousands separator
size	'sm' | 'md' | 'lg' | 'xl'	'lg'	Size variant
showTrend	boolean	true	Show trend indicator
trendColors	{ up?, down?, stable? }	Default colors	Custom trend colors
className	string	-	Additional class

Example with formatting

<LiveCounter
  value={1234567}
  prefix="$"
  decimals={2}
  separator=","
  trend="up"
  size="xl"
/>
// Displays: $1,234,567.00 with up arrow

---

RealtimeDevSettings

Purpose

Developer settings dropdown for switching between polling and WebSocket modes. Useful during development or for users who need to force a specific mode.

Basic usage

import { RealtimeDevSettings } from '@/shared/ui/components/realtime'

export function DashboardHeader() {
  return (
    <header>
      <h1>Dashboard</h1>
      <RealtimeDevSettings />
    </header>
  )
}

Props

Prop	Type	Default	Description
className	string	-	Additional class

---

Usage with realtime data

These components are designed to work with Katalyst's realtime infrastructure:

import { useRealtimeChannel, useRealtimeMode } from '@/shared/infrastructure/realtime'
import { ConnectionStatus, LiveCounter } from '@/shared/ui/components/realtime'

export function RealtimeDashboard() {
  const { mode } = useRealtimeMode()
  const { isConnected, lastMessage } = useRealtimeChannel<{ count: number }>({
    path: '/ws/metrics/realtime',
    channel: 'active-users',
  })

  return (
    <div>
      <ConnectionStatus isConnected={isConnected} mode={mode} />
      <LiveCounter
        value={lastMessage?.data.count ?? null}
        trend="stable"
      />
    </div>
  )
}

Notes

• LiveCounter uses react-countup for smooth animations
• ConnectionStatus uses CSS animations for the pulsing effect
• Both components support dark mode through Tailwind classes

---

Related

• useRealtime Primitives — Core hooks for realtime data
• useRealtime API — Full API reference
• Realtime Data Pattern — Building unified hooks