Client-Side Usage - Upstash Documentation

The useRealtime hook connects your React components to realtime events with full type safety.

Basic Usage

Subscribe to events in any client component:

page.tsx

"use client"

import { useRealtime } from "@upstash/realtime/client"
import type { RealtimeEvents } from "@/lib/realtime"

export default function Page() {
  useRealtime<RealtimeEvents>({
    event: "notification.alert",
    onData(data, channel) {
      console.log("Received:", data)
    },
  })

  return <p>Listening for events...</p>
}

Hook Options

event

string

required

The event to subscribe to (e.g. "notification.alert")

onData

function

required

Callback when an event is received. Receives data and channel as arguments.

channels

string[]

default:"[\"default\"]"

Array of channel names to subscribe to

history

boolean | object

default:"false"

true: Fetch all available history
{ length: number }: Fetch the last N messages
{ since: number }: Fetch messages after a Unix timestamp (in milliseconds)

enabled

boolean

default:"true"

Whether the connection is active. Set to false to disconnect.

maxReconnectAttempts

number

default:"3"

Maximum number of reconnection attempts before giving up

api

object

API configuration: - url: The realtime endpoint URL, defaults to /api/realtime - withCredentials: Whether to send cookies with requests (useful for external backends)

Return Value

The hook returns an object with:

status

ConnectionStatus

Current connection state: "connecting", "connected", "reconnecting", "disconnected", or "error"

page.tsx

const { status } = useRealtime<RealtimeEvents>({
  event: "notification.alert",
  onData: (data, channel) => {},
})

console.log(status)

Connection Control

Enable or disable connections dynamically:

page.tsx

"use client"

import { useState } from "react"
import { useRealtime } from "@upstash/realtime/client"
import type { RealtimeEvents } from "@/lib/realtime"

export default function Page() {
  const [enabled, setEnabled] = useState(true)

  const { status } = useRealtime<RealtimeEvents>({
    enabled,
    event: "notification.alert",
    onData: (data, channel) => {
      console.log(data, channel)
    },
  })

  return (
    <div>
      <button onClick={() => setEnabled((prev) => !prev)}>
        {enabled ? "Disconnect" : "Connect"}
      </button>

      <p>Status: {status}</p>
    </div>
  )
}

Conditional Connections

Connect only when certain conditions are met:

page.tsx

"use client"

import { useRealtime } from "@upstash/realtime/client"
import type { RealtimeEvents } from "@/lib/realtime"
import { useUser } from "@/hooks/auth"

export default function Page() {
  const { user } = useUser()

  useRealtime<RealtimeEvents>({
    enabled: Boolean(user),
    channels: [`user-${user.id}`],
    event: "notification.alert",
    onData: (data, channel) => {
      console.log(data)
    },
  })

  return <p>Notifications {user ? "enabled" : "disabled"}</p>
}

Multiple Channels

Subscribe to multiple channels at once:

page.tsx

"use client"

import { useRealtime } from "@upstash/realtime/client"
import type { RealtimeEvents } from "@/lib/realtime"

export default function Page() {
  useRealtime<RealtimeEvents>({
    channels: ["global", "announcements", "user-123"],
    event: "notification.alert",
    onData(data, channel) {
      console.log(`Message from ${channel}:`, data)
    },
  })

  return <p>Listening to multiple channels</p>
}

Dynamic Channel Management

Add and remove channels dynamically:

page.tsx

"use client"

import { useState } from "react"
import { useRealtime } from "@upstash/realtime/client"
import type { RealtimeEvents } from "@/lib/realtime"

export default function Page() {
  const [channels, setChannels] = useState<string[]>(["lobby"])

  useRealtime<RealtimeEvents>({
    channels,
    event: "chat.message",
    onData(data, channel) {
      console.log(`Message from ${channel}:`, data)
    },
  })

  const joinRoom = (roomId: string) => {
    setChannels((prev) => [...prev, roomId])
  }

  const leaveRoom = (roomId: string) => {
    setChannels((prev) => prev.filter((c) => c !== roomId))
  }

  return (
    <div>
      <p>Active channels: {channels.join(", ")}</p>
      <button onClick={() => joinRoom("room-1")}>Join Room 1</button>
      <button onClick={() => joinRoom("room-2")}>Join Room 2</button>
      <button onClick={() => leaveRoom("lobby")}>Leave Lobby</button>
    </div>
  )
}

Fetch History on Connection

Replay past messages when connecting:

page.tsx

"use client"

import { useState } from "react"
import { useRealtime } from "@upstash/realtime/client"
import type { RealtimeEvents } from "@/lib/realtime"

export default function ChatRoom() {
  const [messages, setMessages] = useState<string[]>([])

  useRealtime<RealtimeEvents>({
    event: "chat.message",
    history: { length: 50 },
    onData(data, channel) {
      // each history item is automatically passed to this handler
      // so you can replay with any logic you like
      setMessages((prev) => [...prev, data])
    },
  })

  return (
    <div>
      {messages.map((msg, i) => (
        <p key={i}>{msg}</p>
      ))}
    </div>
  )
}

Custom API Endpoint

Configure a custom realtime endpoint:

page.tsx

"use client"

import { useRealtime } from "@upstash/realtime/client"
import type { RealtimeEvents } from "@/lib/realtime"

export default function Page() {
  useRealtime<RealtimeEvents>({
    event: "notification.alert",
    api: {
      url: "/api/custom-realtime",
      withCredentials: true,
    },
    onData: (data, channel) => {
      console.log(data)
    },
  })

  return <p>Connected to custom endpoint</p>
}

Use Cases

Live Notifications

Show real-time notifications to users:

notifications.tsx

"use client"

import { useState } from "react"
import { useRealtime } from "@upstash/realtime/client"
import type { RealtimeEvents } from "@/lib/realtime"
import { toast } from "react-hot-toast"
import { useUser } from "@/hooks/auth"

export default function Notifications() {
  const { user } = useUser()

  useRealtime<RealtimeEvents>({
    channels: [`user-${user.id}`],
    event: "notification.alert",
    onData(content, channel) {
      toast(content)
    },
  })

  return <p>Listening for notifications...</p>
}

Realtime Chat

Build a real-time chat:

chat.tsx

"use client"

import { useState } from "react"
import { useRealtime } from "@upstash/realtime/client"
import type { RealtimeEvents } from "@/lib/realtime"
import z from "zod/v4"

type Message = z.infer<RealtimeEvents["chat"]["message"]>

export default function Chat() {
  const [messages, setMessages] = useState<Message[]>([])

  useRealtime<RealtimeEvents>({
    channels: ["room-123"],
    event: "chat.message",
    history: true,
    onData(message, channel) {
      setMessages((prev) => [...prev, message])
    },
  })

  return (
    <div>
      {messages.map((msg, i) => (
        <p key={i}>
          <span className="font-bold">{msg.sender}:</span> {msg.text}
        </p>
      ))}
    </div>
  )
}

Live Dashboard

Update metrics in real-time:

dashboard.tsx

"use client"

import { useQuery, useQueryClient } from "@tanstack/react-query"
import { useRealtime } from "@upstash/realtime/client"
import type { RealtimeEvents } from "@/lib/realtime"

export default function Dashboard() {
  const queryClient = useQueryClient()
  
  const { data: metrics } = useQuery({
    queryKey: ["metrics"],
    queryFn: async () => {
      const res = await fetch("/api/metrics?user=user-123")
      return res.json()
    },
  })

  useRealtime<RealtimeEvents>({
    channels: ["user-123"],
    event: "metrics.update",
    onData() {
      // 👇 invalidate, so react-query refetches
      queryClient.invalidateQueries({ queryKey: ["metrics"] })
    },
  })

  return (
    <div>
      <p>Active Users: {metrics.users}</p>
      <p>Revenue: ${metrics.revenue}</p>
    </div>
  )
}

Collaborative Editing

Sync changes across users:

editor.tsx

"use client"

import { useState } from "react"
import { useRealtime } from "@upstash/realtime/client"
import type { RealtimeEvents } from "@/lib/realtime"

export default function Editor({ documentId }: { documentId: string }) {
  const [content, setContent] = useState("")

  useRealtime<RealtimeEvents>({
    channels: [`doc-${documentId}`],
    event: "document.update",
    history: { length: 1 },
    onData(data, channel) {
      setContent(data.content)
    },
  })

  return <textarea value={content} onChange={(e) => setContent(e.target.value)} />
}

Realtime

​Basic Usage

​Hook Options

​Return Value

​Connection Control

​Conditional Connections

​Multiple Channels

​Dynamic Channel Management

​Fetch History on Connection

​Custom API Endpoint

​Use Cases

​Next Steps

Channels

History

Basic Usage

Hook Options

Return Value

Connection Control

Conditional Connections

Multiple Channels

Dynamic Channel Management

Fetch History on Connection

Custom API Endpoint

Use Cases

Next Steps