Skip to main content

Call & Participant State

You can access call, participant and client state using hooks. These hooks are reactive (their value is updated on WebSocket events and API calls).

Call state

To observe call state you need to provide a Call instance to the StreamCall component.

Let's see an example where we use the useCall, useCallCallingState and useParticipants hooks to display some basic information about the call:

import {
} from '@stream-io/video-react-sdk';

export default function App() {
let call: Call;

return (
<StreamCall call={call}>
<MyCallUI />

const MyCallUI = () => {
const call = useCall();

const { useCallCallingState, useParticipants } = useCallStateHooks();
const callingState = useCallCallingState();
const participants = useParticipants();

return (
<div>Call: {call?.cid}</div>
<div>State: {callingState}</div>
<div>Participants: {participants.length}</div>

This approach makes it possible to access the call state and be notified about changes anywhere in your application without having to manually subscribe to WebSocket events.

The StreamCall component uses the StreamCallProvider under the hood.

Here is an excerpt of the available call state hooks:

useCallThe Call instance that is registered with StreamCall. You need the Call instance to initiate API calls.
useCallBlockedUserIdsThe list of blocked user IDs.
useCallCallingStateProvides information about the call state. For example, RINGING, JOINED or RECONNECTING.
useCallCreatedAtThe time the call was created.
useCallCreatedByThe user that created the call.
useCallCustomDataThe custom data attached to the call.
useCallEgressThe egress information of the call.
useCallEndedByThe user that ended the call.
useCallIngressThe ingress information of the call.
useCallMembersThe list of call members
useCallSessionThe information for the current call session.
useCallSettingsThe settings of the call.
useCallStartedAtThe actual start time of the current call session.
useCallStartsAtThe scheduled start time of the call.
useCallStatsReportWhen stats gathering is enabled, this observable will emit a new value at a regular (configurable) interval.
useCallThumbnailThe thumbnail of the call.
useCallUpdatedAtThe time the call was last updated.
useCameraStateThe camera state of the local participant.
useDominantSpeakerThe participant that is the current dominant speaker of the call.
useHasOngoingScreenShareIt will return true if at least one participant is sharing their screen.
useHasPermissionsReturns true if the local participant has all the given permissions.
useIsCallHLSBroadcastingInProgressIt's true if the call is being broadcasted in HLS mode.
useIsCallLiveIt's true if the call is currently live.
useIsCallRecordingInProgressIt's' true if the call is being recorded.
useIsCallTranscribingInProgressIt's true if the call is being transcribed.
useMicrophoneStateThe microphone state of the local participant.
useOwnCapabilitiesThe capabilities of the local participant.
useScreenShareStateThe screen share state of the local participant.
useSpeakerStateThe speaker state of the local participant.

In your IDE of choice, you can see the full list if you destructure the useCallStateHooks object:

import { useCallStateHooks } from '@stream-io/video-react-sdk';

const {
// ...
} = useCallStateHooks();

Participant state

If you want to display information about the joined participants of the call you can use these hooks:

useLocalParticipantThe local participant is the logged-in user.
useRemoteParticipantsAll participants except the local participant.
useParticipantsAll participants, including local and remote participants.
useParticipantCountThe approximate participant count of the active call. This includes the anonymous users as well, it is computed on the server-side.
useAnonymousParticipantCountThe approximate participant count of anonymous users in the active call.
import { useCallStateHooks, StreamCall } from '@stream-io/video-react-sdk';

export default function App() {
let call: call;

return (
<StreamCall call={call}>
<MyCallUI />

const MyCallUI = () => {
const { useLocalParticipant, useParticipantCount } = useCallStateHooks();
const participantCount = useParticipantCount();
const localParticipant = useLocalParticipant();

return (
<div>Number of participants: {participantCount}</div>
<div>Session ID: {localParticipant.sessionId}</div>

The StreamVideoParticipant object contains the following information:

userThe user object for this participant.
publishedTracksThe track types the participant is currently publishing
joinedAtThe time the participant joined the call.
connectionQualityThe participant's connection quality.
isSpeakingIt's true if the participant is currently speaking.
isDominantSpeakerIt's true if the participant is the current dominant speaker in the call.
audioLevelThe audio level of the participant.
audioStreamThe published audio MediaStream.
videoStreamThe published video MediaStream.
screenShareStreamThe published screen share MediaStream.
screenShareAudioStreamThe published screen share audio MediaStream.
isLocalParticipantIt's true if the participant is the local participant.
pinHolds pinning information.
reactionThe last reaction this user has sent to this call.
viewportVisibilityStateThe viewport visibility state of the participant.

Client state

To observe client state you need to provide a StreamVideoClient instance to the StreamVideo context provider. If you want to observe the connected user you can use the useConnectedUser hook.

Let's see an example:

import {
} from '@stream-io/video-react-sdk';

export default function App() {
let client: StreamVideoClient;

return (
<StreamVideo client={client}>
<MyHeader />

const MyHeader = () => {
const user = useConnectedUser();
return <div>{user ? `Logged in: ${}` : 'Logged out'}</div>;

This approach makes it possible to access the client state and be notified about changes anywhere in your application without having to manually subscribe to WebSocket events.

Here are the list of client-state hooks:

useStreamVideoClientThe StreamVideoClient instance.
useConnectedUserReturns the connected user.
useCallsA list of all notifications about created calls. These calls can be outgoing (I have called somebody) or incoming (somebody has called me).

The UserResponse contains the following properties:

created_atThe time the user was created.
customCustom user data.
deleted_atThe time the user was deleted.
devicesThe registered push notification devices of the user.
idThe id of the user.
imageThe profile image of the user.
nameThe name of the user.
roleThe role of the user.
teamsThe teams the user belongs to.
updated_atThe time when the user was updated.

Did you find this page helpful?