Pin/Unpin Participants - JavaScript

In a live stream setup, you often want to control which participant is actively visible on screen — whether it’s the host, a special guest, or someone screen sharing. To manage this dynamically, the useParticipant hook provides two key methods:

• pin() – Focus on a specific participant’s camera or screen share

• unpin() – Remove that focus and return to the default layout

This allows you to programmatically decide who gets the spotlight in your live stream layout.

pin()

The pin() method makes it easy to bring a host camera or screen share front and center in the broadcast layout. Once pinned, you can write the layout logic to place this host in the primary frame, e.g. fullscreen or in a highlighted position.

let liveStream;

// Initialize Meeting
liveStream = VideoSDK.initMeeting({
  // ...
});

const participants = liveStream.participants;
const participant = participants.get("<participant-id>");

const pinBtn = document.getElementById("pinBtn");
pinBtn.addEventListener("click", () => {
  // unmuteMic Meeting
  participant?.pin();
});

unpin()

When a host is no longer the focus (e.g. their segment is over), you can reset their pinned state using unpin(). This allows your live stream UI to revert to a default grid view or automatically promote the next speaker.

let liveStream;

// Initialize LiveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

const participants = liveStream.participants;
const participant = participants.get("<participant-id>");

const unpinBtn = document.getElementById("unpinBtn");
unpinBtn.addEventListener("click", () => {
  participant?.unpin();
});

Events associated with pin/unpin

Following callbacks are received when a host is pinned or unpinned in the livestream.

• All participants-including all the hosts and audience members will receive a callback on the pin-state-changed event with the data object containg the peerid of the participant who was pinned, the state and pinnedBy values.

let liveStream;

// Initialize LiveStream
liveStream = VideoSDK.initMeeting({
  // ...
});

liveStream.on("pin-state-changed", (data) => {
  const { peerId, state, pinnedBy } = data;
  console.log("onPinStateChanged");
});

info

• Based on the pin-state-changed event, you should update your live stream layout for all participants (including the audience) to reflect the current pinned participant. This means conditionally rendering the pinned participant in the main view or spotlight area across all clients.

API Reference

The API references for all the methods and events utilized in this guide are provided below.

• pin
• unpin