Realtime

Presence

Share state between users with Realtime Presence.

Let's explore how to implement Realtime Presence to track state between multiple users.

Usage

You can use the Supabase client libraries to track Presence state between users.

How Presence works

Presence lets each connected client publish a small piece of state—called a “presence payload”—to a shared channel. Supabase stores each client’s payload under a unique presence key and keeps a merged view of all connected clients.

When any client subscribes, disconnects, or updates their presence payload, Supabase triggers one of three events:

  • sync — the full presence state has been updated
  • join — a new client has started tracking presence
  • leave — a client has stopped tracking presence

The complete presence state returned by presenceState() looks like this:

1
2
3
4
{  "client_key_1": [{ "userId": 1, "typing": false }],  "client_key_2": [{ "userId": 2, "typing": true }]}

Initialize the client

Go to your Supabase project's API Settings and grab the URL and anon public API key.

1
2
3
4
5
6
import {  } from '@supabase/supabase-js'const  = 'https://<project>.supabase.co'const  = '<sb_publishable_... or anon key>'const  = (, )

Sync and track state

Listen to the sync, join, and leave events triggered whenever any client joins or leaves the channel or changes their slice of state:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
const  = .('room_01')  .('presence', { : 'sync' }, () => {    const  = .()    .('sync', )  })  .('presence', { : 'join' }, ({ ,  }) => {    .('join', , )  })  .('presence', { : 'leave' }, ({ ,  }) => {    .('leave', , )  })  .()

Sending state

You can send state to all subscribers using track():

1
2
3
4
5
6
7
8
9
10
11
12
13
const  = .('room_01')const  = {  : 'user-1',  : new ().(),}.(async () => {  if ( !== 'SUBSCRIBED') { return }  const  = await .()  .()})

A client will receive state from any other client that is subscribed to the same topic (in this case room_01). It will also automatically trigger its own sync and join event handlers.

Stop tracking

You can stop tracking presence using the untrack() method. This will trigger the sync and leave event handlers.

1
2
3
4
5
6
const  = async () => {  const  = await .()  .()}()

Presence options

You can pass configuration options while initializing the Supabase Client.

Presence key

By default, Presence will generate a unique UUIDv1 key on the server to track a client channel's state. If you prefer, you can provide a custom key when creating the channel. This key should be unique among clients.

1
2
3
4
5
6
7
8
9
10
import {  } from '@supabase/supabase-js'const  = ('SUPABASE_URL', 'SUPABASE_PUBLISHABLE_KEY')const  = .('test', {  : {    : {      : 'userId-123',    },  },})