Skip to content
Cloudflare Docs

Remote Participants

This guide explains how to access participant data, display videos, handle events, and manage participant permissions in your RealtimeKit meetings.

The participant object contains all information related to a particular participants, including information about the grid and each participants media streams, name, and state variables. It is accessible via meeting.participants.

Properties

Metadata properties

  • id - The participantId of the participant (aka peerId)
  • userId - The userId of the participant
  • name - The participant's name
  • picture - The participant's picture (if any)
  • customParticipantId - An arbitrary ID that can be set to identify the participant
  • isPinned - Set to true if the participant is pinned
  • presetName - Name of the preset associated with the participant

Media properties

  • videoEnabled - Set to true if the participant's camera is on
  • audioEnabled - Set to true if the participant is unmuted
  • screenShareEnabled - Set to true if the participant is sharing their screen
  • videoTrack - The video track of the participant
  • audioTrack - The audio track of the participant
  • screenShareTracks - The video and audio tracks of the participant's screen share

Access participant properties

Use the useRealtimeKitSelector hook to access properties:

// Number of participants joined in the meeting
const participantCount = useRealtimeKitSelector((m) => m.participants.count);


// Number of pages available in paginated mode
const pageCount = useRealtimeKitSelector((m) => m.participants.pageCount);


// Maximum number of participants in active state
const maxActiveCount = useRealtimeKitSelector(
  (m) => m.participants.maxActiveParticipantsCount,
);


// ParticipantId of the last participant who spoke
const lastActiveSpeaker = useRealtimeKitSelector(
  (m) => m.participants.lastActiveSpeaker,
);

Access participant object

You can fetch a participant from the participant maps.

// Get a specific participant
const participant = useRealtimeKitSelector((m) =>
  m.participants.joined.get(participantId),
);


// Access participant properties
const participantName = participant?.name;
const isVideoEnabled = participant?.videoEnabled;
const isAudioEnabled = participant?.audioEnabled;

Participant Maps

All participants are stored under meeting.participants. These do not include the local user.

The meeting.participants object contains the following maps:

  • joined - All participants currently in the meeting (excluding the local user)
  • waitlisted - All participants waiting to join the meeting
  • active - All participants whose media is subscribed to (participants that should be displayed on screen)
  • pinned - All pinned participants in the meeting

If you are building a video/audio grid, use the active map. To display a list of all participants, use the joined map.

Each participant in these maps is of type RTKParticipant.

Use the useRealtimeKitSelector hook to access participant maps:

import { useRealtimeKitSelector } from "@cloudflare/realtimekit-react";


// Get all joined participants
const joinedParticipants = useRealtimeKitSelector((m) => m.participants.joined);


// Get active participants (those on screen)
const activeParticipants = useRealtimeKitSelector((m) => m.participants.active);


// Get pinned participants
const pinnedParticipants = useRealtimeKitSelector((m) => m.participants.pinned);


// Get waitlisted participants
const waitlistedParticipants = useRealtimeKitSelector(
  (m) => m.participants.waitlisted,
);

View Modes

The view mode indicates whether participants are populated in ACTIVE_GRID mode or PAGINATED mode.

  • ACTIVE_GRID mode - Participants are automatically replaced in meeting.participants.active based on who is speaking or who has their video turned on
  • PAGINATED mode - Participants in meeting.participants.active are fixed. Use setPage() to change the active participants

Set view mode

Use the useRealtimeKitClient hook to access the meeting object:

import { useRealtimeKitClient } from "@cloudflare/realtimekit-react";


const [meeting] = useRealtimeKitClient();


// Set the view mode to paginated
await meeting.participants.setViewMode("PAGINATED");


// Set the view mode to active grid
await meeting.participants.setViewMode("ACTIVE_GRID");

Set page in paginated mode

import { useRealtimeKitClient } from "@cloudflare/realtimekit-react";


const [meeting] = useRealtimeKitClient();


// Switch to second page
await meeting.participants.setPage(2);

Monitor view mode

const viewMode = useRealtimeKitSelector((m) => m.participants.viewMode);
const currentPage = useRealtimeKitSelector((m) => m.participants.currentPage);

Host Controls

The participant object allows the host several controls. These can be selected while creating the host preset.

Media controls

With the correct permissions, the host can disable media for remote participants.

import { useRealtimeKitClient } from "@cloudflare/realtimekit-react";


const [meeting] = useRealtimeKitClient();
const participant = meeting.participants.joined.get(participantId);


// Disable a participant's video stream
participant.disableVideo();


// Disable a participant's audio stream
participant.disableAudio();


// Kick a participant from the meeting
participant.kick();

Waiting room controls

The waiting room allows the host to control which users can join your meeting and when. They can either choose to accept or reject the request.

You can also automate this flow so that users join the meeting automatically when the host joins the meeting, using presets.

Accept waiting room request

import { useRealtimeKitClient } from "@cloudflare/realtimekit-react";


const [meeting] = useRealtimeKitClient();


await meeting.participants.acceptWaitingRoomRequest(participantId);

Reject waiting room request

import { useRealtimeKitClient } from "@cloudflare/realtimekit-react";


const [meeting] = useRealtimeKitClient();


await meeting.participants.rejectWaitingRoomRequest(participantId);

Pin participants

The host can choose to pin or unpin participants to the grid.

import { useRealtimeKitClient } from "@cloudflare/realtimekit-react";


const [meeting] = useRealtimeKitClient();
const participant = meeting.participants.joined.get(participantId);


// Pin a participant
await participant.pin();


// Unpin a participant
await participant.unpin();

Update participant permissions

The host can modify the permissions for a participant. Permissions for a participant are defined by their preset.

First, find the participant(s) you want to update.

JavaScript
const participantIds = meeting.participants.joined
  .toArray()
  .filter((e) => e.name.startsWith("John"))
  .map((p) => p.id);

Use the updatePermissions method to modify the permissions for the participant.

JavaScript
// Allow file upload permissions in public chat
const newPermissions = {
  chat: {
    public: {
      files: true,
    },
  },
};


meeting.participants.updatePermissions(participantIds, newPermissions);

The following permissions can be modified:

TypeScript
interface UpdatedPermissions {
  polls?: {
    canCreate?: boolean;
    canVote?: boolean;
  };
  plugins?: {
    canClose?: boolean;
    canStart?: boolean;
  };
  chat?: {
    public?: {
      canSend?: boolean;
      text?: boolean;
      files?: boolean;
    };
    private?: {
      canSend?: boolean;
      text?: boolean;
      files?: boolean;
    };
  };
}

Display participant videos

To play a participant's video track on a <video> element:

import { useRealtimeKitClient } from "@cloudflare/realtimekit-react";


const [meeting] = useRealtimeKitClient();


// Get the video element
const videoElement = document.getElementById("participant-video");


// Get the participant
const participant = meeting.participants.joined.get(participantId);


// Register the video element
participant.registerVideoElement(videoElement);


// Clean up when the video element is no longer needed
participant.deregisterVideoElement(videoElement);

For local user preview (video not sent to other users):

meeting.self.registerVideoElement(videoElement, true);