RTCPeerConnection: connectionstatechange event

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨May 2023⁩.

The connectionstatechange event is sent to the onconnectionstatechange event handler on an RTCPeerConnection object after a new track has been added to an RTCRtpReceiver which is part of the connection. The new connection state can be found in connectionState, and is one of the string values: new, connecting, connected, disconnected, failed, or closed.

This event is not cancelable and does not bubble.

Syntax

Use the event name in methods like addEventListener(), or set an event handler property.

addEventListener("connectionstatechange", (event) => { }) onconnectionstatechange = (event) => { }

Event type

A generic Event.

Examples

For an RTCPeerConnection named peerConnection, this example uses addEventListener() to handle changes to the connectivity of the WebRTC session. It calls an app-defined function called setOnlineStatus() to update a status display.

peerConnection.addEventListener("connectionstatechange", (event) => { switch (peerConnection.connectionState) { case "new": case "connecting": setOnlineStatus("Connecting…"); break; case "connected": setOnlineStatus("Online"); break; case "disconnected": setOnlineStatus("Disconnecting…"); break; case "closed": setOnlineStatus("Offline"); break; case "failed": setOnlineStatus("Error"); break; default: setOnlineStatus("Unknown"); break; } });

You can also create a handler for the connectionstatechange event using the RTCPeerConnection.onconnectionstatechange property:

peerConnection.onconnectionstatechange = (ev) => { switch (peerConnection.connectionState) { case "new": case "connecting": setOnlineStatus("Connecting…"); break; // … default: setOnlineStatus("Unknown"); break; } };