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 {
  Call,
  StreamCall,
  useCall,
  useCallStateHooks,
} from '@stream-io/video-react-sdk';

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

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

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

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

  return (
    <div>
      <div>Call: {call?.cid}</div>
      <div>State: {callingState}</div>
      <div>Participants: {participants.length}</div>
    </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 is a context provider that makes the call state available to all child components. The useCall hook returns the Call instance that is registered with StreamCall. You need the Call instance to initiate API calls.

Call State Hooks

Here is an excerpt of the available call state hooks:

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 {
  useCallMembers,
  useDominantSpeaker,
  useParticipants,
  useLocalParticipant,
  useIsCallRecordingInProgress,
  // ...
} = useCallStateHooks();

Participant state

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

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

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

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

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

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

The StreamVideoParticipant object contains the following information:

The SDK also provides a few utility functions that help you to work with participants:

import {
  hasAudio,
  hasVideo,
  hasScreenShare,
  hasScreenShareAudio,
  isPinned,
  useCallStateHooks,
} from '@stream-io/video-react-sdk';

// example usage
const { useParticipants } = useCallStateHooks();
const participants = useParticipants();

// check if the participant has audio, video, screen share or screen share audio
const [participant] = participants;
const hasAudioOn = hasAudio(participant);
const hasVideoOn = hasVideo(participant);
const hasScreenShareOn = hasScreenShare(participant);
const hasScreenShareAudioOn = hasScreenShareAudio(participant);
const isPinnedOn = isPinned(participant);

// participants with a specific role
const hosts = participants.filter((p) => p.roles.includes('host'));

// participants that publish video and audio
const videoParticipants = participants.filter(
  (p) => hasVideo(p) && hasAudio(p),
);

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 {
  useConnectedUser,
  StreamVideo,
  StreamVideoClient,
} from '@stream-io/video-react-sdk';

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

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

const MyHeader = () => {
  const user = useConnectedUser();
  return <div>{user ? `Logged in: ${user.name}` : '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 is the list of client-state hooks:

The connectedUser object contains the following properties: