React Hooks API Reference

Interfaces

Type Aliases

TrackWithPeerAndDimensions

Ƭ TrackWithPeerAndDimensions: Object

Type declaration

Name	Type
`height?`	`number`
`peer`	`HMSPeer`
`track?`	`HMSVideoTrack` \| `HMSScreenVideoTrack`
`width?`	`number`

hooksErrHandler

Ƭ hooksErrHandler: (err: Error, method?: string) => void

Type declaration

▸ (err, method?): void

use this to control how errors are handled within a function exposed by a hook. By default this only logs the error to the console, and can be overridden for any other behaviour. For example (err) => throw err; will ensure that any error is thrown back to the caller when the function is called.

Parameters

Name	Type
`err`	`Error`
`method?`	`string`

Returns

void

usePaginatedParticipantsInput

Ƭ usePaginatedParticipantsInput: HMSPeerListIteratorOptions

useParticipantsParams

Ƭ useParticipantsParams: Object

Type declaration

Name	Type	Description
`metadata`	`Record`<`string`, `any`>	To filter by particular by metadata. only supports `{ isHandRaised: true }` for now
`role`	`HMSRoleName`	To filter by particular role
`search`	`string`	To filter by name/role (partial match)

Functions

HMSRoomProvider

▸ HMSRoomProvider<T>(«destructured»): FunctionComponentElement<ProviderProps<null | HMSContextProviderProps>>

top level wrapper for using react sdk hooks. This doesn't have any mandatory arguments, if you are already initialising the sdk on your side, you can pass in the primitives from there as well to use hooks for react part of your code.

Type parameters

Name	Type
`T`	extends `HMSGenericTypes` = { `sessionStore`: `Record`<`string`, `any`> }

Parameters

Name	Type
`«destructured»`	`PropsWithChildren`<`HMSRoomProviderProps`<`T`>>

Returns

FunctionComponentElement<ProviderProps<null | HMSContextProviderProps>>

getPeersWithTiles

▸ getPeersWithTiles(peers, tracks, includeScreenShareForPeer, filterNonPublishingPeers?): TrackWithPeer[]

given list of peers and all tracks in the room, get a list of tile objects to show in the UI

Parameters

Name	Type	Default value	Description
`peers`	`HMSPeer`[]	`undefined`
`tracks`	`Record`<`string`, `HMSTrack`>	`undefined`
`includeScreenShareForPeer`	(`peer`: `HMSPeer`) => `boolean`	`undefined`	fn will be called to check whether to include screenShare for the peer in returned tiles
`filterNonPublishingPeers`	`boolean`	`true`	by default a peer with no tracks won't be counted towards final tiles

Returns

TrackWithPeer[]

throwErrorHandler

▸ throwErrorHandler(err, method?): void

pass in this error handler to get the error thrown back to the UI for further handling, showing toast etc.

Parameters

Name	Type
`err`	`Error`
`method?`	`string`

Returns

void

useAVToggle

▸ useAVToggle(handleError?): useAVToggleResult

Use this hook to implement mute/unmute for audio and video. isAllowedToPublish can be used to decide whether to show the toggle buttons in the UI.

Parameters

Name	Type	Default value	Description
`handleError`	`hooksErrHandler`	`logErrorHandler`	to handle any error during toggle of audio/video

Returns

useAVToggleResult

useAudioLevelStyles

▸ useAudioLevelStyles(«destructured»): void

This hook can be used to apply css properties on an element based on the current audio level for the passed in track. It doesn't return the audio level as it's optimised for performance. As audio level could be changing frequently we want to minimise the number of components an audio level change causes to re render. An e.g. use of this hook will be to apply box-shadow on parent tile based on audio level.

Parameters

Name	Type
`«destructured»`	`Object`
› `getStyle`	(`level`: `number`) => `Record`<`string`, `string`>
› `ref`	`RefObject`<`any`>
› `trackId?`	`string`

Returns

void

useAutoplayError

▸ useAutoplayError(): useAutoplayErrorResult

Use this hook to show a UI(modal or a toast) when autoplay is blocked by browser and allow the user to unblock the browser autoplay block

Returns

useAutoplayErrorResult

useAwayNotifications

▸ useAwayNotifications(): Object

Returns

Object

Name	Type
`requestPermission`	() => `Promise`<`void`>
`showNotification`	(`title`: `string`, `options?`: `NotificationOptions`) => `void`

useCustomEvent

▸ useCustomEvent<T>(«destructured»): useCustomEventResult<T>

A generic function to implement custom events in your UI. The data to be sent to remote is expected to be a serializable JSON. The serialization and deserialization is taken care of by the hook.

Type parameters

Name
`T`

Parameters

Name	Type
`«destructured»`	`useCustomEventInput`<`T`>

Returns

useCustomEventResult<T>

useDevices

▸ useDevices(handleError?): useDevicesResult

This hook can be used to implement a UI component which allows the user to manually change their audio/video device. It returns the list of all devices as well as the currently selected one. The input devices will be returned based on what the user is allowed to publish, so a audio only user won't get the audioInput field. This can be used to show the UI dropdowns properly.

Note:

Browsers give access to the list of devices only if the user has given permission to access them
Changing devices manually work best in combination with remembering the user's selection for the next time, do pass the rememberDeviceSelection flag at time of join for this to happen.

Parameters

Name	Type	Default value	Description
`handleError`	`hooksErrHandler`	`logErrorHandler`	error handler for any errors during device change

Returns

useDevicesResult

useEmbedShare

▸ useEmbedShare(resetConfig?): useEmbedShareResult

Parameters

Name	Type	Description
`resetConfig?`	() => `void`	Callback that implements cleanup after Embed sharing stops. It is an optional parameter.

Returns

useEmbedShareResult

useEmbedShareResult

useHMSActions

▸ useHMSActions(): IHMSActions<{}>

Returns

IHMSActions<{}>

useHMSNotifications

▸ useHMSNotifications<T>(type?): null | HMSNotificationInCallback<T>

useHMSNotifications is a read only hook which gives the latest notification(HMSNotification) received.

Type parameters

Name	Type
`T`	extends `HMSNotificationTypeParam`

Parameters

Name	Type	Description
`type?`	`T`	can be a string or an array of string for the types of notifications to listen to. If an array is passed either declare it outside the functional component or use a useMemo to make sure its reference stays same across rerenders for performance reasons.

Returns

null | HMSNotificationInCallback<T>

useHMSStatsStore

▸ useHMSStatsStore<StateSlice>(selector, equalityFn?): undefined | StateSlice

Type parameters

Name
`StateSlice`

Parameters

Name	Type	Default value
`selector`	`StateSelector`<`HMSStatsStore`, `StateSlice`>	`undefined`
`equalityFn`	`EqualityChecker`<`StateSlice`>	`shallow`

Returns

undefined | StateSlice

useHMSStore

▸ useHMSStore<StateSlice>(selector, equalityFn?): StateSlice

useHMSStore is a read only hook which can be passed a selector to read data. The hook can only be used in a component if HMSRoomProvider is present in its ancestors.

Type parameters

Name
`StateSlice`

Parameters

Name	Type	Default value
`selector`	`StateSelector`<`HMSStore`<{}>, `StateSlice`>	`undefined`
`equalityFn`	`EqualityChecker`<`StateSlice`>	`shallow`

Returns

StateSlice

useHMSVanillaNotifications

▸ useHMSVanillaNotifications(): undefined | IHMSNotifications

Returns

undefined | IHMSNotifications

useHMSVanillaStore

▸ useHMSVanillaStore(): IHMSReactStore<HMSStore<{}>>

useHMSVanillaStore is a read only hook which returns the vanilla HMSStore. Usage:


const hmsStore = useHMSVanillaStore();
const dominantSpeaker = hmsStore.getState(selectDominantSpeaker);

Note: There's no need to use the vanilla hmsStore in React components. This is used in rare cases where the store needs to be accessed outside a React component. For almost every case, useHMSStore would get the job done.

Returns

IHMSReactStore<HMSStore<{}>>

usePDFShare

▸ usePDFShare(resetConfig?): usePDFShareResult

Parameters

Name	Type	Description
`resetConfig?`	() => `void`	Callback that implements cleanup after PDF sharing stops. Typically used to reset the currently selected PDF file or URL in your state. It is an optional parameter.

Returns

usePDFShareResult

usePDFShareResult

usePaginatedParticipants

▸ usePaginatedParticipants(options): Object

Parameters

Name	Type
`options`	`HMSPeerListIteratorOptions`

Returns

Object

Name	Type
`hasNext`	() => `boolean`
`loadMorePeers`	() => `Promise`<`void`>
`loadPeers`	() => `Promise`<`void`>
`peers`	`HMSPeer`[]
`total`	`number`

useParticipantList

▸ useParticipantList(): Object

Returns

Object

Name	Type
`isConnected`	`undefined` \| `boolean`
`participantsByRoles`	`Record`<`string`, `HMSPeer`[]>
`peerCount`	`number`
`roles`	`string`[]

useParticipants

▸ useParticipants(params?): Object

This can be used to get the total count of participants in the room, participants filtered by role or metadata with isHandRaised or the entire participants if no params are passed

Parameters

Name	Type
`params?`	`useParticipantsParams`

Returns

Object

Name	Type
`isConnected`	`undefined` \| `boolean`
`participants`	`HMSPeer`[]
`peerCount`	`number`
`rolesWithParticipants`	(`undefined` \| `string`)[]

usePreviewJoin

▸ usePreviewJoin(«destructured»): usePreviewResult

This hook can be used to build a preview UI component, this lets you call preview every time the passed in token changes. This hook is best used in combination with useDevices for changing devices, useAVToggle for muting/unmuting and useAudioLevelStyles for showing mic audio level to the user. Any device change or mute/unmute will be carried across to join.

Parameters

Name	Type
`«destructured»`	`usePreviewInput`

Returns

Parameters

Name	Type	Default value
`isMobile`	`boolean`	`false`

Returns

Object

Name	Type
`iframeRef`	`MutableRefObject`<`null` \| `HTMLIFrameElement`>
`isAdmin`	`boolean`
`isOwner`	`boolean`
`open`	`boolean`
`toggle`	`undefined` \| () => `Promise`<`void`>

RTMP Streaming & Browser Recording HMSTranscript

Have a suggestion? Recommend changes ->