# 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](/video/docs/react/ui-components/core/stream-call/).

<admonition type="note">

For the best experience, please make sure that the provided `Call` instance is loaded
and connected to our backend: [Load Call](/video/docs/react/guides/joining-and-creating-calls/#load-call/).

Otherwise, `call.state` and the call state hooks will provide empty values.

</admonition>

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

```tsx
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:

| Name                                                                           | Description                                                                                                   |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| `useCall`                                                                      | The `Call` instance that is registered with `StreamCall`. You need the `Call` instance to initiate API calls. |
| `useCallBlockedUserIds`                                                        | The list of blocked user IDs.                                                                                 |
| [`useCallCallingState`](/video/docs/react/guides/calling-state-and-lifecycle/) | Provides information about the call state. For example, `RINGING`, `JOINED` or `RECONNECTING`.                |
| [`useCallClosedCaptions`](/video/docs/react/ui-cookbook/closed-captions/)      | The closed captions of the call.                                                                              |
| `useCallCreatedAt`                                                             | The time the call was created.                                                                                |
| `useCallCreatedBy`                                                             | The user that created the call.                                                                               |
| `useCallCustomData`                                                            | The custom data attached to the call.                                                                         |
| `useCallEgress`                                                                | The egress information of the call.                                                                           |
| `useCallEndedBy`                                                               | The user that ended the call.                                                                                 |
| `useCallIngress`                                                               | The ingress information of the call.                                                                          |
| `useCallMembers`                                                               | The list of call members                                                                                      |
| `useCallSession`                                                               | The information for the current call session.                                                                 |
| `useCallSettings`                                                              | The settings of the call.                                                                                     |
| `useCallStartedAt`                                                             | The actual start time of the current call session.                                                            |
| `useCallStartsAt`                                                              | The scheduled start time of the call.                                                                         |
| [`useCallStatsReport`](/video/docs/react/advanced/stats/)                      | When stats gathering is enabled, this observable will emit a new value at a regular (configurable) interval.  |
| `useCallThumbnail`                                                             | The thumbnail of the call.                                                                                    |
| `useCallUpdatedAt`                                                             | The time the call was last updated.                                                                           |
| `useCameraState`                                                               | The camera state of the local participant.                                                                    |
| `useDominantSpeaker`                                                           | The participant that is the current dominant speaker of the call.                                             |
| `useHasOngoingScreenShare`                                                     | It will return `true` if at least one participant is sharing their screen.                                    |
| `useHasPermissions`                                                            | Returns `true` if the local participant has all the given permissions.                                        |
| `useIsCallCaptioningInProgress`                                                | It's `true` if the call is being close-captioned.                                                             |
| `useIsCallHLSBroadcastingInProgress`                                           | It's `true` if the call is being broadcasted in HLS mode.                                                     |
| `useIsCallLive`                                                                | It's `true` if the call is currently live.                                                                    |
| `useIsCallRecordingInProgress`                                                 | It's `true` if the call is being recorded.                                                                    |
| `useIsCallTranscribingInProgress`                                              | It's `true` if the call is being transcribed.                                                                 |
| `useMicrophoneState`                                                           | The microphone state of the local participant.                                                                |
| `useOwnCapabilities`                                                           | The capabilities of the local participant.                                                                    |
| `useScreenShareState`                                                          | The screen share state of the local participant.                                                              |
| `useSpeakerState`                                                              | The speaker state of the local participant.                                                                   |

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

```ts
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:

| Name                           | Description                                                                                                                                                                                   |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `useLocalParticipant`          | The local participant is the logged-in user.                                                                                                                                                  |
| `useRemoteParticipants`        | All participants except the local participant.                                                                                                                                                |
| `useParticipants`              | All participants, including local and remote participants.                                                                                                                                    |
| `useRawParticipants`           | A version of `useParticipants` that is not affected by paticipant sort settings and thus causes less component updates.                                                                       |
| `useParticipantCount`          | The approximate participant count of the active call. This includes the [anonymous users](/video/docs/react/guides/client-auth/#anonymous-users/) as well, it is computed on the server-side. |
| `useAnonymousParticipantCount` | The approximate participant count of anonymous users in the active call.                                                                                                                      |

```tsx
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 has the following properties:

| Name                      | Description                                                                      |
| ------------------------- | -------------------------------------------------------------------------------- |
| `audioLevel`              | The audio level of the participant (determined on the server).                   |
| `audioStream`             | The audio `MediaStream`.                                                         |
| `audioVolume`             | The audio volume level of the participant (overridable local audioVolume level). |
| `connectionQuality`       | The participant's connection quality.                                            |
| `custom`                  | The participant's custom data. Comes from the `custom` field of the user object. |
| `image`                   | The image of the participant.                                                    |
| `isDominantSpeaker`       | It's `true` if the participant is the current dominant speaker in the call.      |
| `isLocalParticipant`      | It's `true` if the participant is the local participant.                         |
| `isSpeaking`              | It's `true` if the participant is currently speaking.                            |
| `joinedAt`                | The time the participant joined the call.                                        |
| `name`                    | The name of the participant.                                                     |
| `pausedTracks`            | The tracks that are currently server-side paused for the local participant.      |
| `pin`                     | Holds pinning information.                                                       |
| `publishedTracks`         | The track types the participant is currently publishing                          |
| `reaction`                | The last reaction this user has sent to this call.                               |
| `roles`                   | The roles of the participant in this call.                                       |
| `sessionId`               | The identifier of the participant within the existing call session               |
| `screenShareAudioStream`  | The screen share audio `MediaStream`.                                            |
| `screenShareStream`       | The screen share `MediaStream`.                                                  |
| `userId`                  | The user ID of the participant.                                                  |
| `videoStream`             | The video `MediaStream`.                                                         |
| `viewportVisibilityState` | The viewport visibility state of the participant.                                |

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

```ts
import {
  hasAudio,
  hasVideo,
  hasScreenShare,
  hasScreenShareAudio,
  hasPausedTrack,
  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);
const isVideoPaused = hasPausedTrack(participant, "videoTrack");

// 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:

```tsx
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:

| Name                   | Description                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `useStreamVideoClient` | The `StreamVideoClient` instance.                                                                                                                                               |
| `useConnectedUser`     | Returns the connected user. Holds the server-side data of the connected user.                                                                                                   |
| `useCalls`             | A list of all tracked calls. These calls can be outgoing (I have called somebody) or incoming (somebody has called me). Loaded calls (`call.get()`) are also part of this list. |

The `connectedUser` object contains the following properties:

| Name         | Description                                           |
| ------------ | ----------------------------------------------------- |
| `created_at` | The time the user was created.                        |
| `custom`     | Custom user data.                                     |
| `deleted_at` | The time the user was deleted.                        |
| `devices`    | The registered push notification devices of the user. |
| `id`         | The id of the user.                                   |
| `image`      | The profile image of the user.                        |
| `name`       | The name of the user.                                 |
| `role`       | The role of the user.                                 |
| `teams`      | The teams the user belongs to.                        |
| `updated_at` | The time when the user was updated.                   |

---

This page was last updated at 2025-08-15T14:16:42.893Z.

For the most recent version of this documentation, visit [https://getstream.io/video/docs/react/guides/call-and-participant-state/](https://getstream.io/video/docs/react/guides/call-and-participant-state/).