Components / Call
@peerkit-dev/call
Two-person video calls with camera, microphone, and screen share controls.
Use CallController from @peerkit-dev/call-core, the <peerkit-call> element, or PeerKitCall. Both people publish and receive camera and microphone on a PeerKit call session. The camera and microphone stay off until Start call.
JavaScript and Web Components
npm install @peerkit-dev/call-core @peerkit-dev/sdkReact
npm install @peerkit-dev/call @peerkit-dev/sdk react react-domLive demo
PeerKitCall
Starting a two-person video call…
Preparing the call…
Installation
Install @peerkit-dev/call-core for vanilla JavaScript or the <peerkit-call> element. Install @peerkit-dev/call when the page is React. The React package depends on Call Core and re-exports CallController. Published versions are Call Core 0.1.0 and React Call 0.1.1.
JavaScript and Web Components
npm install @peerkit-dev/call-core @peerkit-dev/sdk
React
npm install @peerkit-dev/call @peerkit-dev/sdk react react-dom
Requires @peerkit-dev/sdk 0.1.9 or newer. Create the session on your server with media: "call". Pass each person an invitation. Both people publish and receive camera and microphone. The call asks for the camera and microphone only after Start call.
Vanilla JavaScript
CallController holds call status, camera, microphone, screen share, devices, and errors. subscribe and getSnapshot are how a page reads that state. Call sync() after constructing the controller. attachPreview, attachRemoteVideo, attachRemoteScreen, attachLocalScreen, and attachAudio bind the media elements. dispose() drops listeners and, when this controller created the session, disconnects it.
Call start() from a click or another user interaction. start() calls play() on the audio and video elements before any await, which keeps that activation for the camera and microphone prompts and for remote playback. Calling start() from the constructor, from page load, or through autoStart can lose the gesture. autoStart defaults to false. sync() does not connect or open the camera or microphone.
import { CallController } from "@peerkit-dev/call-core";
const preview = document.querySelector("video#preview");
const remote = document.querySelector("video#remote");
const screen = document.querySelector("video#screen");
const audio = document.querySelector("audio");
const call = new CallController(() => ({
invitationUrl: "https://peerkit.dev/s#inv_…",
localName: "Alex",
remoteName: "Jordan",
onCallEnd: (reason) => console.log(reason),
onError: (error) => console.error(error.code, error.message),
}));
call.attachPreview(preview);
call.attachRemoteVideo(remote);
call.attachRemoteScreen(screen);
call.attachAudio(audio);
call.subscribe(() => {
const snapshot = call.getSnapshot();
console.log(snapshot.statusLabel, snapshot.cameraState, snapshot.screenState);
});
call.sync();
document.querySelector("#start")?.addEventListener("click", () => {
void call.start();
});
document.querySelector("#share")?.addEventListener("click", () => {
void call.toggleScreenShare();
});
document.querySelector("#end")?.addEventListener("click", () => {
call.end();
});HTML
Import @peerkit-dev/call-core/element to register <peerkit-call>. Importing @peerkit-dev/call-core alone does not register the element. The element renders in light DOM, adds the class pk-call, and owns the video and audio elements.
The Start call button calls start() from that click. Set labels.you and labels.participant for the two names. Set sessionController before the element connects.
<script type="module">
import "@peerkit-dev/call-core/element";
</script>
<peerkit-call id="call"></peerkit-call>
<script type="module">
const call = document.querySelector("peerkit-call");
call.invitationUrl = "https://peerkit.dev/s#inv_…";
call.labels = { you: "Alex", participant: "Jordan" };
call.addEventListener("peerkit-call-end", (event) => {
console.log(event.detail);
});
call.addEventListener("peerkit-screen", (event) => {
console.log(event.detail.state, event.detail.active);
});
</script>Browser script
dist/element.global.js is a self-contained script. It registers <peerkit-call> and assigns CallController and PeerSessionController to the global PeerkitCall. The script includes the SDK. An application that already loads @peerkit-dev/sdk should use the ESM entry instead and pass that PeerKitSession in.
<peerkit-call id="call"></peerkit-call>
<script src="https://cdn.jsdelivr.net/npm/@peerkit-dev/call-core@0.1.0/dist/element.global.js"></script>
<script>
const call = document.querySelector("peerkit-call");
call.invitationUrl = "https://peerkit.dev/s#inv_…";
call.labels = { you: "Alex", participant: "Jordan" };
</script>React
PeerKitCall uses the same controller. Its Start call button calls start() from the click. Leave autoStart off so the camera and microphone request stays on that interaction.
import { PeerKitCall } from "@peerkit-dev/call";
export function Call({ invitationUrl }: { invitationUrl: string }) {
return (
<PeerKitCall
invitationUrl={invitationUrl}
localName="Alex"
remoteName="Jordan"
localAvatar="https://example.com/alex.png"
theme="dark"
onCallEnd={(reason) => console.log(reason)}
onError={(error) => console.error(error.code, error.message)}
/>
);
}Two-person call
- Create one session with
media: "call"and two invitations. - Both people publish a camera and a microphone, and both receive the other person.
- Each person mutes the microphone and turns the camera off independently.
- Either person can share a screen when the browser supports it. Display audio is not sent.
A directional camera session stays media: "video". That mode still sends the camera one way. PeerKit Voice stays media: "audio". A call does not use the two-way voice allowlist.
Custom interface
usePeerKitCall exposes status, connection, presence, local and remote media, devices, duration, and errors. Keep the video and audio elements mounted and pass previewRef, remoteVideoRef, remoteScreenRef, localScreenRef, and audioRef. Call startCall() from the button click. PeerKitCallControls renders the standard buttons. CallVideo, CallParticipant, CallStatus, and CallTimer are the layout pieces.
import { usePeerKitCall } from "@peerkit-dev/call";
export function CallButtons({ invitationUrl }: { invitationUrl: string }) {
const call = usePeerKitCall({ invitationUrl });
return (
<div>
<video ref={call.previewRef} autoPlay muted playsInline />
<video ref={call.remoteVideoRef} autoPlay muted playsInline />
<video ref={call.remoteScreenRef} autoPlay muted playsInline />
<video ref={call.localScreenRef} autoPlay muted playsInline />
<audio ref={call.audioRef} autoPlay />
<p>{call.statusLabel} · {call.durationLabel}</p>
<button type="button" onClick={() => void call.startCall()}>Start call</button>
<button type="button" onClick={() => void call.toggleMute()}>
{call.muted ? "Unmute" : "Mute"}
</button>
<button type="button" onClick={() => call.toggleCamera()}>
{call.cameraEnabled ? "Turn camera off" : "Turn camera on"}
</button>
<button type="button" onClick={() => void call.toggleScreenShare()}>
{call.screenSharing ? "Stop sharing" : "Share screen"}
</button>
<button type="button" onClick={() => call.endCall()}>End call</button>
</div>
);
}Shared session
Pass a PeerKitSession another part of the page already owns. Create that session with media: "call". end() and dispose() leave that session connected. disconnectOnEnd defaults to true when this controller created the session, and to false when a session is provided. With the default, end() on a provided session mutes the microphone and playback. It disables the camera only when this controller published that camera, and it stops screen sharing only when this controller started it. It does not call stop() on a track owned by another controller. Set disconnectOnEnd to true when End call should disconnect that provided session. manageConnection controls whether dispose() disconnects a session this controller created. It defaults to true for that owned session. dispose() does not stop external tracks. Remove a view with dispose(), and end the call with end().
import { PeerKitSession } from "@peerkit-dev/sdk";
import { CallController } from "@peerkit-dev/call-core";
const session = new PeerKitSession({
signalingUrl: "wss://signal.example",
token: "participant-token",
media: "call",
});
const call = new CallController(() => ({ session }));
call.attachPreview(document.querySelector("#preview"));
call.attachRemoteVideo(document.querySelector("#remote"));
call.attachAudio(document.querySelector("audio"));
call.sync();
document.querySelector("#start")?.addEventListener("click", () => {
void call.start();
});For one owner shared with Chat or Share, construct a PeerSessionController with media: "call" and pass it as sessionController. Call does not create that session, and it does not call dispose() on the owner. Call sessions.sync() first. start() needs that owner's session to exist already, then the click opens the camera and microphone. sessions.dispose() disconnects a session that owner created.
Import PeerSessionController from @peerkit-dev/chat-core/session when the page should not load the call element. @peerkit-dev/call-core re-exports it.
import { CallController, PeerSessionController } from "@peerkit-dev/call-core";
const sessions = new PeerSessionController(() => ({
invitationUrl: "https://peerkit.dev/s#inv_…",
media: "call",
}));
sessions.sync();
const call = new CallController(() => ({ sessionController: sessions }));
call.attachAudio(document.querySelector("audio"));
call.sync();
document.querySelector("#start")?.addEventListener("click", () => {
void call.start();
});Features
- Ready, connecting, waiting, connected, reconnecting, ended, and error states.
- Camera and microphone permission, mute, camera on and off, and device selection after Start call.
- Speaker selection where the browser implements
setSinkId. - Screen sharing starts and stops from its own control. Display audio is not mixed into the call. If the browser stops the camera track during the share, stopping the share publishes the camera again when it was on before the share. Turning the camera off during the share leaves it off.
- Call duration, connection status, and remote camera or microphone presence. An open data channel alone does not count as the other person.
- A provided session and a shared
PeerSessionControllerstay connected when the call view goes away. - Names, avatars, theme, visible controls, and connection and error callbacks are configurable.
Events
React callbacks fire when the value changes. A rerender does not repeat them. The custom element emits the same changes as bubbling events: peerkit-call-start, peerkit-call-end, peerkit-connection, peerkit-ready, peerkit-error, peerkit-participant, peerkit-camera, peerkit-microphone, peerkit-device, and peerkit-screen. Payloads omit tokens and signaling URLs.
| Callback | Fires when |
|---|---|
onCallStart | Start call finishes connecting. Permission errors also call onError and leave the call open. |
onCallEnd | The local person ends the call ("local") or the server ends the session ("remote"). Once per call. |
onConnectionChange | Signaling state changes. Repeated identical states are ignored. |
onParticipantJoined | A remote camera or microphone is live. participantId is set when a data peer is open. A data connection alone does not fire this event. |
onParticipantLeft | Remote camera and remote audio are both gone. An open data connection alone does not count as presence. |
onMicrophoneChange | Mute, microphone state, or microphone id changes after start. |
onCameraChange | Camera enabled flag, camera state, or camera id changes after start. |
onDeviceChange | A camera, microphone, or speaker is selected, or that device disappears. |
onScreenShareChange | Local screen-share state changes. |
onError | Call, camera, microphone, speaker, screen, or session error. Camera denials say to allow camera access. |
Props
React props and CallController options use these names. The element reads names from labels.you and labels.participant. className and style are React.
| Prop | Purpose |
|---|---|
invitationUrl | Redeem a hosted invitation when the call starts and this controller creates the session. |
signalingUrl and token | Join with credentials you already redeemed. |
session | Reuse an existing call PeerKitSession. Left connected on end unless disconnectOnEnd is true. |
sessionController | Share a PeerSessionController created with media: "call". Call does not create or dispose that owner. |
disconnectOnEnd | Disconnect when the local person ends the call. Default true for an owned session and false for a provided session. |
manageConnection | Disconnect a session this controller created when it is disposed. Default true for that session. |
autoStart | Call start() from sync(). Default false, so the camera and microphone request stays on a click. |
localName and remoteName | Labels on the two people. Defaults are You and Participant. The element uses labels instead of these property names. |
controls | Hide mute, camera, microphone, camera devices, speaker, screen, timer, or end. |
theme | light or dark. |
Styling
Pass className, style, and theme ("light" or "dark"). Override the variables below. The package does not draw a PeerKit mark.
.my-call {
--peerkit-call-accent: #0d9488;
--peerkit-call-button-bg: #0d9488;
--peerkit-call-button-ink: #ffffff;
--peerkit-call-bg: #f8fafc;
--peerkit-call-radius: 20px;
--peerkit-call-font: "Avenir Next", sans-serif;
--peerkit-call-gap: 16px;
--peerkit-call-pad: 20px;
}Stable selectors: .pk-call, .pk-call__header, .pk-call__title, .pk-call__status, .pk-call__timer, .pk-call__stage, .pk-call__participant (data-role local, remote, or screen), .pk-call__video, .pk-call__avatar, .pk-call__controls, .pk-call__button, .pk-call__select, .pk-call__error.
Spacing uses --peerkit-call-gap and --peerkit-call-pad. Corners use --peerkit-call-radius. Type uses --peerkit-call-font, which inherits by default. The stage stacks controls below 560px of component width.
Browser compatibility
- Chrome, Edge, Firefox, Safari, iPhone Safari, and Android Chrome can place the call on HTTPS or localhost.
- Camera and microphone permission are requested from the Start call click. Screen sharing is requested from the Share screen click.
- Speaker selection appears only where
setSinkIdexists. Firefox, Safari, and iPhone Safari hide it. - iPhone Safari plays video inline. Start call calls
play()inside the click so autoplay can proceed. Enable sound appears if playback is still blocked. - Screen sharing stays hidden when
getDisplayMediais missing, which is the usual iPhone Safari case. System audio from the display picker is not sent. - Unplugging a selected camera, microphone, or speaker refreshes the list and fires
onDeviceChange.