RealtimeChannel
import { RealtimeChannel } from "https://esm.sh/@supabase/supabase-js@2.110.7/dist/index.d.mts";A channel is the basic building block of Realtime and narrows the scope of data flow to subscribed clients. You can think of a channel as a chatroom where participants are able to see who's online and send and receive messages.
§Constructors
Creates a channel that can broadcast messages, sync presence, and listen to Postgres changes.
The topic determines which realtime stream you are subscribing to. Config options let you enable acknowledgement for broadcasts, presence tracking, or private channels.
Using supabase-js (recommended)
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://xyzcompany.supabase.co', 'your-publishable-key')
const channel = supabase.channel('room1')
channel
.on('broadcast', { event: 'cursor-pos' }, (payload) => console.log(payload))
.subscribe()
Standalone import for bundle-sensitive environments
import RealtimeClient from '@supabase/realtime-js'
const client = new RealtimeClient('https://xyzcompany.supabase.co/realtime/v1', {
params: { apikey: 'your-publishable-key' },
})
const channel = new RealtimeChannel('realtime:public:messages', { config: {} }, client)
§Properties
§Methods
Sends a broadcast message explicitly via REST API.
This method always uses the REST API endpoint regardless of WebSocket connection state. Useful when you want to guarantee REST delivery or when gradually migrating from implicit REST fallback.
Payloads that are ArrayBuffer or ArrayBufferView (e.g. Uint8Array) are sent as
application/octet-stream; all other payloads are JSON-encoded.
The name of the broadcast event
Payload to be sent (required)
Options including timeout
Promise resolving to object with success status, and error details if failed
Listen for presence events on this channel — when peers join, leave, or sync presence state.
Listen for Postgres database changes (insert / update / delete) streamed over this channel.
Listen for broadcast messages sent on this channel.
One of "broadcast", "presence", or "postgres_changes".
Custom object specific to the Realtime feature detailing which payloads to receive.
Function to be invoked when event handler is triggered.
Listen for system events on this channel.
The payload follows the RealtimeSystemPayload shape. Opt in to the replication-ready
notification with config.broadcast.replication_ready: true when creating the channel, then
watch for payload.status === 'ok' to know the Postgres replication connection is ready.
Know when the replication connection is ready
const channel = supabase.channel('room1', {
config: { broadcast: { replication_ready: true } },
})
channel
.on('postgres_changes', { event: '*', schema: 'public', table: 'messages' }, (payload) => {
console.log('Change received!', payload)
})
.on('system', {}, (payload) => {
if (payload.extension === 'system' && payload.status === 'ok') {
console.log('Replication connection is ready:', payload.message)
}
})
.subscribe()
Returns the current presence state for this channel.
The shape is a map keyed by presence key (for example a user id) where each entry contains the tracked metadata for that user.
Sends a message into the channel.
Arguments to send to channel
The type of event to send
The name of the event being sent
Payload to be sent
Options to be used during the send process
Send a message via websocket
const channel = supabase.channel('room1')
channel.subscribe((status) => {
if (status === 'SUBSCRIBED') {
channel.send({
type: 'broadcast',
event: 'cursor-pos',
payload: { x: Math.random(), y: Math.random() },
})
}
})
Send a message via REST
const channel = supabase.channel('room1')
try {
await channel.httpSend('cursor-pos', { x: Math.random(), y: Math.random() })
} finally {
await supabase.removeChannel(channel)
}
Subscribe registers your client with the server.
The optional callback receives a status and, on failure, an err argument.
Log the full err so its cause, name, and any structured fields aren't hidden
behind err.message.
Handling errors
supabase.channel('room1').subscribe((status, err) => {
if (status === 'CHANNEL_ERROR' || status === 'TIMED_OUT') {
// Log the full error: its `cause` often holds the underlying reason.
console.error(status, err)
}
})
Sends the supplied payload to the presence tracker so other subscribers can see that this
client is online. Use untrack to stop broadcasting presence for the same key.
Tracking makes this client visible to other subscribers immediately, regardless of this
channel's config.presence.enabled setting or whether it has a presence listener — that
flag only affects whether this client receives presence updates from others (and, on
RLS-protected channels, whether it's authorized to do so).
Leaves the channel.
Unsubscribes from server events, and instructs channel to terminate on server. Triggers onClose() hooks.
To receive leave acknowledgements, use the a receive hook to bind to the server ack, ie:
channel.unsubscribe().receive("ok", () => alert("left!") )
Removes the current presence state for this client.