useBroadcastChannel

Docs

useBroadcastChannel

Share live messages across tabs with a small React wrapper around the BroadcastChannel API, including message state, cleanup, and error handling.

Installation

pnpm dlx uselab@latest add use-broadcast-channel

Usage

import { useBroadcastChannel } from "@/hooks/use-broadcast-channel"
 
export function PresencePing() {
  const { lastMessage, postMessage } =
    useBroadcastChannel<string>("presence-room")
 
  return (
    <div className="space-y-2">
      <button onClick={() => postMessage("editor-opened")}>Send ping</button>
      <p>{lastMessage || "No messages yet"}</p>
    </div>
  )
}

API Reference

`useBroadcastChannel(name, options?)`

Parameters

Name	Type	Description	Optional
`name`	`string`	Channel name shared by every tab that should communicate.	No
`options`	`UseBroadcastChannelOptions<T>`	Optional callbacks for received messages and receive errors.	Yes

Return value

The hook returns an object { isSupported, isClosed, lastMessage, error, postMessage, close }:

Name	Type	Description
`isSupported`	`boolean`	Whether `BroadcastChannel` exists in the current environment.
`isClosed`	`boolean`	Whether the current channel instance has been closed.
`lastMessage`	`T \| null`	Most recent received message payload.
`error`	`Error \| null`	Last send or receive error.
`postMessage`	`(message: T) => boolean`	Sends a message and returns whether dispatch succeeded.
`close`	`() => void`	Closes the channel and detaches message handlers.

Options

interface UseBroadcastChannelOptions<T> {
  onMessage?: (data: T) => void
  onMessageError?: (event: Event) => void
}

onMessage: Runs whenever a message is received on the active channel.
onMessageError: Runs when the browser reports a message deserialization or delivery failure.

Notes

This hook is a good fit for cross-tab presence, ephemeral notifications, optimistic sync, or “draft changed in another tab” warnings.
BroadcastChannel is best for same-origin tabs and windows. It does not replace server pub/sub for cross-device communication.
If you need persistence, pair it with storage or a backend event stream instead of treating broadcast messages as durable state.

useBreakpoint useCallbackRef

On This Page

Installation
Usage
API Reference
- useBroadcastChannel(name, options?)
- Options
Notes

Contribute

Usage

import { useBroadcastChannel } from "@/hooks/use-broadcast-channel"
 
export function PresencePing() {
  const { lastMessage, postMessage } =
    useBroadcastChannel<string>("presence-room")
 
  return (
    <div className="space-y-2">
      <button onClick={() => postMessage("editor-opened")}>Send ping</button>
      <p>{lastMessage || "No messages yet"}</p>
    </div>
  )
}

API Reference

useBroadcastChannel(name, options?)

Parameters

Name	Type	Description	Optional
`name`	`string`	Channel name shared by every tab that should communicate.	No
`options`	`UseBroadcastChannelOptions<T>`	Optional callbacks for received messages and receive errors.	Yes

Return value

The hook returns an object { isSupported, isClosed, lastMessage, error, postMessage, close }:

Name	Type	Description
`isSupported`	`boolean`	Whether `BroadcastChannel` exists in the current environment.
`isClosed`	`boolean`	Whether the current channel instance has been closed.
`lastMessage`	`T \| null`	Most recent received message payload.
`error`	`Error \| null`	Last send or receive error.
`postMessage`	`(message: T) => boolean`	Sends a message and returns whether dispatch succeeded.
`close`	`() => void`	Closes the channel and detaches message handlers.

Options

interface UseBroadcastChannelOptions<T> {
  onMessage?: (data: T) => void
  onMessageError?: (event: Event) => void
}

onMessage: Runs whenever a message is received on the active channel.

onMessageError: Runs when the browser reports a message deserialization or delivery failure.

Notes

This hook is a good fit for cross-tab presence, ephemeral notifications, optimistic sync, or “draft changed in another tab” warnings.

BroadcastChannel is best for same-origin tabs and windows. It does not replace server pub/sub for cross-device communication.

If you need persistence, pair it with storage or a backend event stream instead of treating broadcast messages as durable state.