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
  "client_key_1": [{ "userId": 1, "typing": false }],
3
  "client_key_2": [{ "userId": 2, "typing": true }]
4
}

Initialize the client#

Get the Project URL and key from the project's Connect dialog.

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

Sync and track state#

1
const roomOne = supabase.channel('room_01')
2
3
roomOne
4
  .on('presence', { event: 'sync' }, () => {
5
    const newState = roomOne.presenceState()
6
    console.log('sync', newState)
7
  })
8
  .on('presence', { event: 'join' }, ({ key, newPresences }) => {
9
    console.log('join', key, newPresences)
10
  })
11
  .on('presence', { event: 'leave' }, ({ key, leftPresences }) => {
12
    console.log('leave', key, leftPresences)
13
  })
14
  .subscribe()

Sending state#

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

1
const roomOne = supabase.channel('room_01')
2
3
const userStatus = {
4
  user: 'user-1',
5
  online_at: new Date().toISOString(),
6
}
7
8
roomOne.subscribe(async (status) => {
9
  if (status !== 'SUBSCRIBED') { return }
10
11
  const presenceTrackStatus = await roomOne.track(userStatus)
12
  console.log(presenceTrackStatus)
13
})

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
const untrackPresence = async () => {
2
  const presenceUntrackStatus = await roomOne.untrack()
3
  console.log(presenceUntrackStatus)
4
}
5
6
untrackPresence()

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
import { createClient } from '@supabase/supabase-js'
2
const supabase = createClient('SUPABASE_URL', 'SUPABASE_PUBLISHABLE_KEY')
3
4
const channelC = supabase.channel('test', {
5
  config: {
6
    presence: {
7
      key: 'userId-123',
8
    },
9
  },
10
})