@zoom/videosdk-ui-toolkit

Zoom Video SDK UI toolkit for web

Use of this SDK is subject to our Terms of Use.

The Zoom Video SDK UI toolkit is a prebuilt video chat user interface powered by the Zoom Video SDK.

Installation

In your frontend project, install the Video SDK UI toolkit:

$ npm install @zoom/videosdk-ui-toolkit --save

Or, for Vanilla JS applications, download the package and add it to your project. Then, add the following script and CSS style to the HTML page you want the UI toolkit to live on:

<link rel="stylesheet" href="@zoom/videosdk-ui-toolkit/dist/videosdk-ui-toolkit.css">
<script src="@zoom/videosdk-ui-toolkit/index.js" type="module"></script>

Setup

For webpack / single page applications like Angular, Vue, React, etc, import the UI toolkit, package and styles:

import uitoolkit from '@zoom/videosdk-ui-toolkit'
import '@zoom/videosdk-ui-toolkit/dist/videosdk-ui-toolkit.css'

In Angular, CSS can't be imported directly into the component, instead, add the styles to your angular.json file in the styles array:

"styles": [
  "node_modules/@zoom/videosdk-ui-toolkit/dist/videosdk-ui-toolkit.css",
]

Or, for Vanilla JS applications, import the JS file directly:

import uitoolkit from './@zoom/videosdk-ui-toolkit/index.js'

JS imports work if your script tag has the type="module" attribute.

UI toolkit CDN is coming soon to make vanilla JS usage easier.

Usage

Join Session

To join a Video SDK session, create an HTML container that it will be rendered in:

<div id='sessionContainer'></div>

Create your Video SDK session config object, with your Video SDK JWT, and Video SDK session info, the features you want to render, and any options you want to specify.

var config = {
  videoSDKJWT: '',
  sessionName: 'SessionA',
  userName: 'UserA',
  sessionPasscode: 'abc123',
  streamUrl: 'rtmp://a.rtmp.siteofyourchoice.com',
  streamKey: 'xxxx-xxxx-xxxx-xxxx',
  broadcastUrl: 'https://studio.siteofyourchoice.com/livestreaming',
  crDisclaimer: 'Cloud recording disclaimer for the UIToolkit to prompt',
  lttDisclaimer: 'Live Transscription and Translation disclaimer for the UIToolkit to prompt',
  livestreamDisclaimer: 'Live streaming disclaimer for the UIToolkit to prompt',
  disableCaptionsOnJoin: true,
  features: ['preview', 'video', 'audio', 'share', 'chat', 'users', 'livestream', 'pstn', 'ltt', 'recording', 'settings', 'feedback'],
  options: { init: {}, audio: {}, video: {}, share: {}},
  virtualBackground: {
    allowVirtualBackground: true,
    allowVirtualBackgroundUpload: true,
    virtualBackgrounds: ['https://images.unsplash.com/photo-1715490187538-30a365fa05bd?q=80&w=1945&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D']
  }
}

If you pass a string to the config object disclaimers(cr, ltt, and livestream), you are telling the UIToolkit that it will handle prompting the disclaimers passed when the corresponding event triggers. If you leave the fields empty, the developer is responsible for the disclaimer UI and the prompting these disclaimers when the event is triggered. You can listen for these events and pass in a callback via the code below:

const client = ZoomVideo.createClient();

client.on('recording-change', () => {});
client.on('caption-status', () => {});
client.on('live-stream-status', () => {});

Because the VideoClient follows the singleton pattern, you can call createClient() to retrieve the same client object the UIToolKit uses to control the underlying Zoom Video SDK. You can then utilize any functions offered by the base Zoom Video SDK. Please note, that certain components in the UIToolKit depend on state stored and passed within its underlying components so calling certain functions outside of the UIToolKit can introduce unexpected behavior in the UI.

Currently, we support the following features:

features[]	Description
preview	Enables the preview flow, let's the end user choose their preferred video, microphone, speaker, and background before joining the session.
video	Enable the video layout, and to send and receive video.
audio	Show the audio button on the toolbar, and to send and receive audio.
share	Show the screen share button on the toolbar, and to send and receive screen share content.
chat	Show the chat button on the toolbar, and to send and receive session chats.
livestream	Show the livestream button on the toolbar to start or end a livestream.
users	Show the users button on the toolbar, and to see the list of users in the session.
pstn	Show the invite by phone feature in the users interface.
crc	Show the invite by SIP feature in the users interface.
ltt	Show the Live Transcription button on the toolbar. The user can start transcription and hide or show the captions.
recording	Show the Cloud Recording button on the toolbar.
settings	Show the settings button on the toolbar, and to configure virtual background, camera, microphone, and speaker devices, and see session quality statistics.
feedback	Show the feedback flow after the session is left or ended. The user can rate the session (1-5 stars) and report feedback to Zoom.

We also support setting specific properties for the Video SDK init, audio, video, and share options.

options{}	Properties	Default	Description
init	enforceMultipleVideos enforceVirtualBackground webEndpoint	false false zoom.us	Enables rendering multiple videos if SharedArrayBuffer is off. Enables virtual background if SharedArrayBuffer is off. Specifies the Zoom real-time media environment.
audio	backgroundNoiseSuppression originalSound syncButtonsOnHeadset	true false false	Zoom's AI background noise suppression. Sends sound exactly as it's captured (opposite of background noise suppression). Enables headset buttons like mute/unmute to work within supported browsers.
video	originalRatio virtualBackground	true false true null	Sends video exactly as it's captured. If false, Zoom crops it to 16:9. Sets a default virtual background for the user.
share	controls displaySurface hideShareAudioOption optimizedForSharedVideo	null null false false	Enables configuring specific content to share within supported browsers Enables configuring specific share surfaces within supported browsers. Enables or disables the share computer audio option within supported browsers. Prioritizes frame rate over resolution for better screen sharing of videos.

You may notice some options irrelevant for the UI Toolkit use case are not exposed (for example skipJsMedia and alternativeNameForVideoPlayer), or are defaulted on (for example leaveOnPageUnload and patchJsMedia) with no option to change them. For feedback or requests relating to exposing additional init, audio, video, and share options from the Video SDK, please share your use case here.

Virtual backgrounds can also be configured further like providing a list of available backgrounds, allowing the user to upload their own background, or disabling virtual backgrounds completely. To set a default, specific virtual background for a user, use the options -> video -> virtualBackground approach mentioned above.

virtualBackground{}	Default	Description
allowVirtualBackground	true	Enables users to choose their virtual background from the backgrounds list.
allowVirtualBackgroundUpload	true	Enables users to upload their own virtual background.
virtualBackgrounds	[]	Sets the list of available virtual backgrounds.

After you have configured your session, call the uitoolkit.joinSession function, passing in the container reference, and the Video SDK session config object:

var sessionContainer = document.getElementById('sessionContainer')

uitoolkit.joinSession(sessionContainer, config)

Leave Session

To leave a Video SDK session, the user can click the red leave button. The host can also end the session for everyone, by clicking their red end button.

You can also leave a session programmatically by calling the uitoolkit.closeSession function:

uitoolkit.closeSession(sessionContainer)

Event Listeners

To subscribe to event listeners, define a callback function that you want to execute when the respective event is triggered:

var sessionJoined = (() => {
  console.log('session joined')
})

var sessionClosed = (() => {
  console.log('session closed')
})

Then, pass the callback function to the respective on event listener (after calling the uitoolkit.joinSession function).

uitoolkit.onSessionJoined(sessionJoined)

uitoolkit.onSessionClosed(sessionClosed)

To unsubscribe to event listeners, pass the callback function to the respective off event listener.

uitoolkit.offSessionJoined(sessionJoined)

uitoolkit.offSessionClosed(sessionClosed)

Currently, we support the following event listeners:

Event Listener	Description
onSessionJoined	Fires when the user joins the session successfully.
onSessionClosed	Fires when the session is left or ended.
offSessionJoined	Unsubscribes to the onSessionJoined event.
offSessionClosed	Unsubscribes to the onSessionClosed event.

Build with UI Toolkit components

Zoom's UI Toolkit now offers Developers powerful built-in components that are ready to use. Currently, we offer the following components:

Component	Description
uitoolkit-components	Gives UI Toolkit components access to Video SDK session and context.
controls-component	Enables users to envoke actions such as muting, starting video, screen sharing, and more.
video-component	Displays user videos and screen sharing.
chat-component	Displays session and 1:1 chat messages.
users-component	Displays the list of users in a session and allows hosts to moderate the session.
settings-component	Displays the session settings and allows users to configure virtual background, camera, microphone, and speaker devices, and see session quality statistics.

Show UI Toolkit components

When building with UI Toolkit components, the uitoolkit-components component is a required wrapper around the UI Toolkit components. To begin, create an HTML container that it will be rendered in:

<div id='uitoolkitContainer'></div>

Then, call the uitoolkit.showUitoolkitComponents function, passing in the container reference, and the Video SDK session config object:

var uitoolkitContainer = document.getElementById('uitoolkitContainer')

uitoolkit.showUitoolkitComponents(uitoolkitContainer, config)

Hide UI Toolkit components

To close the wrapper, call the uitoolkit.hideUiToolkitComponents function while passing in the container reference:

uitoolkit.hideUiToolkitComponents(providerContainer)

Show the controls component

The controls component is a required component that enables users to control their video call experience. To render the controls component, create and HTML container and pass it into the uitoolkit.showControlsComponent function:

<div id='uitoolkitContainer'>
  ...
  <div id='controlsContainer'></div>
  ...
</div>

var controlsContainer = document.getElementById('controlsContainer')

uitoolkit.showControlsComponent(controlsContainer)

Hide the controls component

To close the Control Bar Component, call the uitoolkit.hideControlsComponent function while passing in the container reference:

uitoolkit.hideControlsComponent(controlsContainer)

Show the video component

To render the video component, create and HTML container and pass it into the uitoolkit.showVideoComponent function:

<div id='uitoolkitContainer'>
  ...
  <div id='videoContainer'></div>
  ...
</div>

var videoContainer = document.getElementById('videoContainer')

uitoolkit.showVideoComponent(videoContainer)

Hide the video component

To close the video component, call the uitoolkit.hideVideoComponent function while passing in the container reference:

uitoolkit.hideVideoComponent(videoContainer)

Show the chat component

To render the Chatkit, create and HTML container and pass it into the uitoolkit.showChatComponent function:

<div id='uitoolkitContainer'>
  ...
  <div id='chatContainer'></div>
  ...
</div>

var chatContainer = document.getElementById('chatContainer')

uitoolkit.showChatComponent(chatContainer)

Hide the chat component

To close the chat component, call the uitoolkit.hideChatComponent function while passing in the container reference:

uitoolkit.hideChatComponent(chatContainer)

Show the users component

To render the users component, create and HTML container and pass it into the uitoolkit.showUsersComponent function:

<div id='uitoolkitContainer'>
  ...
  <div id='usersContainer'></div>
  ...
</div>

var usersContainer = document.getElementById('usersContainer')

uitoolkit.showUsersComponent(usersContainer)

Hide the users component

To close the users component, call the uitoolkit.hideUsersComponent function while passing in the container reference:

uitoolkit.hideUsersComponent(usersContainer)

Show the settings component

To render the settings component, create and HTML container and pass it into the uitoolkit.showSettingsComponent function:

<div id='uitoolkitContainer'>
  ...
  <div id='settingsContainer'></div>
  ...
</div>

var settingsContainer = document.getElementById('settingsContainer')

uitoolkit.showSettingsComponent(settingsContainer)

Hide the settings component

To close the settings component, call the uitoolkit.hideSettingsComponent function while passing in the container reference:

uitoolkit.hideSettingsComponent(settingsContainer)

Cleaning up the session

Once your session has ended, we recommend properly cleaning up the UI Toolkit so users can join subsequent sessions. You can easily do this by using the onSessionClosed event listener. Simply call each component's respective hide function to properly remove each component from the DOM. See the following code snippet for an example:

  ...
  uitoolkit.onSessionClosed(sessionClosed)
  ...

  function sessionClosed {
    uitoolkit.hideSettingsComponent(settingsContainer)
    uitoolkit.hideUsersComponent(usersContainer)
    uitoolkit.hideControlsComponent(controlsContainer)
    uitoolkit.hideVideoComponent(videoContainer)
    uitoolkit.hideChatComponent(chatContainer)
    uitoolkit.hideUitoolkitComponents(sessionContainer)
  }

Sample Apps

• Video SDK UI Toolkit Angular Sample
• Video SDK UI Toolkit React Sample
• Video SDK UI Toolkit Vue.js Sample
• Video SDK UI Toolkit JavaScript Sample
• Video SDK Auth Sample (Node.js)
• Webhook Sample (Node.js)

Need help?

If you're looking for help, try Developer Support or our Developer Forum. Priority support is also available with Premier Developer Support plans.