forrealtime

useRealtime

Subscribe to channels and receive typed events in React components.

useRealtime subscribes to one or more channels and fires a callback for each matching event.

import { useState } from "react";
import { useRealtime } from "./realtime";

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

  const { status } = useRealtime({
    channels: ["default"],
    events: ["notification.alert", "chat.message"],
    onData(payload) {
      if (payload.event === "notification.alert") {
        setMessages((prev) => [...prev, `alert: ${payload.data}`]);
      }

      if (payload.event === "chat.message") {
        setMessages((prev) => [
          ...prev,
          `${payload.data.user}: ${payload.data.text}`,
        ]);
      }
    },
  });

  return (
    <div>
      <p>Status: {status}</p>
      <pre>{JSON.stringify(messages, null, 2)}</pre>
    </div>
  );
}

Options

OptionTypeDefaultDescription
channelsstring[]["default"]Channel names to subscribe to
eventsstring[]all eventsEvent names to filter on (e.g. ["notification.alert"])
onData(payload) => voidCallback for each typed message
enabledbooleantrueSet to false to pause the subscription

Returned state

PropertyTypeValues
statusstring"connecting", "connected", "disconnected", "error"

On this page