oniceconnectionstatechange

Oniceconnectionstatechange is a WebRTC event handler property of the RTCPeerConnection interface. It is invoked whenever the ICE connection state changes during the process of establishing, maintaining, or closing a peer-to-peer connection.

The ICE connection state describes the progress of connectivity checks and data path availability. Typical values include new, checking, connected, completed, disconnected, failed, and closed. The new state is the initial value; checking means the ICE agent is performing connectivity checks; connected indicates a usable path has been found; completed means all checks have finished with at least one connected pair; disconnected means the path was lost; failed indicates an error in establishing connectivity; and closed means the connection has been closed.

Usage involves assigning a handler to the oniceconnectionstatechange property. In the handler, you typically read the current state from the RTCPeerConnection’s iceConnectionState property and react accordingly—for example updating the user interface, attempting renegotiation, or tearing down the connection if the state reaches failed or closed. A common pattern is to log or switch behavior based on the current state as shown by pc.iceConnectionState.

Notes and behavior: the event is fired any time the iceConnectionState changes, and the state progression may vary between browsers and networks. It is separate from onicegatheringstatechange, which reports changes to the ICE candidate gathering process. Relying on iceConnectionState provides a practical view of the connectivity status, enabling responsive handling of connectivity issues.

See also RTCPeerConnection and ICE (Interactive Connectivity Establishment).