Handling Events


Client SDKs use events to communicate with the application changes that are taking place in the room.

There are two kinds of events, room events and participant events. Room events are emitted from the main Room object, reflecting any change in the room. Participant events are emitted from each Participant, when that specific participant has changed.

Room events is generally a superset of participant events. As you can see, some events are fired on both Room and Participant; this is intentional. This duplication is designed to make it easier to componentize your application. For example, if you have a UI component that renders a participant, it should only listen to events scoped to that participant.

Declarative UI

Event handling can be quite complicated in a real-time, multi-user system. Participants could be joining and leaving, each publishing tracks or muting them. To simplify this, LiveKit has built-in support for declarative UI in majority of our SDKs.

With declarative UI, you would specify the how the UI should look given a particular state, without having to worry about the sequence of transformations to apply. Modern frameworks are highly efficient at detecting changes and rendering only what's changed.

We offer a few hooks and components that makes working with React much simpler.

  • useParticipant - maps participant events to state
  • useTracks - returns the current state of the specified audio or video track
  • VideoTrack - React component that renders a video track
  • RoomAudioRenderer - React component that renders the sound of all audio tracks
const Stage = () => {
const tracks = useTracks([Track.Source.Camera, Track.Source.ScreenShare]);
return (
{/* ... */}
// Render all video
{tracks.map((track) => {
<VideoTrack trackRef={track} />;
// and all audio tracks.
<RoomAudioRenderer />
function ParticipantList() {
// Render a list of all participants in the room.
const participants = useParticipants();
<ParticipantLoop participants={participants}>
<ParticipantName />


This table captures a consistent set of events that are available across platform SDKs. In addition to what's listed here, there may be platform-specific events on certain platforms.

EventDescriptionRoom EventParticipant Event
ParticipantConnectedA RemoteParticipant joins after the local participant.x
ParticipantDisconnectedA RemoteParticipant leavesx
ReconnectingThe connection to the server has been interrupted and it's attempting to reconnect.x
ReconnectedReconnection has been successfulx
DisconnectedDisconnected from room due to the room closing or unrecoverable failurex
TrackPublishedA new track is published to room after the local participant has joinedxx
TrackUnpublishedA RemoteParticipant has unpublished a trackxx
TrackSubscribedThe LocalParticipant has subscribed to a trackxx
TrackUnsubscribedA previously subscribed track has been unsubscribedxx
TrackMutedA track was muted, fires for both local tracks and remote tracksxx
TrackUnmutedA track was unmuted, fires for both local tracks and remote tracksxx
LocalTrackPublishedA local track was published successfullyxx
LocalTrackUnpublishedA local track was unpublishedxx
ActiveSpeakersChangedCurrent active speakers has changedx
IsSpeakingChangedThe current participant has changed speaking statusx
ConnectionQualityChangedConnection quality was changed for a Participantxx
ParticipantMetadataChangedA participant's metadata was updated via server APIxx
RoomMetadataChangedMetadata associated with the room has changedx
DataReceivedData received from another participant or serverxx
TrackStreamStateChangedIndicates if a subscribed track has been paused due to bandwidthxx
TrackSubscriptionPermissionChangedOne of subscribed tracks have changed track-level permissions for the current participantxx
ParticipantPermissionsChangedWhen the current participant's permissions have changedxx