You're browsing the documentation for v3.x. For v2.x, click here.

The Socket instance (client-side)

Besides emitting and listening to events, the Socket instance has a few attributes that may be of use in your application:

Socket#id

Each new connection is assigned a random 20-characters identifier.

This identifier is synced with the value on the server-side.

// server-side
io.on("connection", (socket) => {
console.log(socket.id); // x8WIv7-mJelg7on_ALbx
});

// client-side
socket.on("connect", () => {
console.log(socket.id); // x8WIv7-mJelg7on_ALbx
});

socket.on("disconnect", () => {
console.log(socket.id); // undefined
});

Socket#connected

This attribute describes whether the socket is currently connected to the server.

socket.on("connect", () => {
console.log(socket.connected); // true
});

socket.on("disconnect", () => {
console.log(socket.connected); // false
});

Lifecycle

Lifecycle diagram

Events

  • connect

This event is fired by the Socket instance upon connection / reconnection.

socket.on("connect", () => {
// ...
});

Please note that you shouldn’t register event handlers in the connect handler itself, as a new handler will be registered every time the Socket reconnects:

// BAD
socket.on("connect", () => {
socket.on("data", () => { /* ... */ });
});

// GOOD
socket.on("connect", () => {
// ...
});

socket.on("data", () => { /* ... */ });
  • connect_error

This event is fired when the server does not accept the connection (in a middleware function).

You need to manually reconnect. You might need to update the credentials:

// either by directly modifying the `auth` attribute
socket.on("connect_error", () => {
socket.auth.token = "abcd";
socket.connect();
});

// or if the `auth` attribute is a function
const socket = io({
auth: (cb) => {
cb(localStorage.getItem("token"));
}
});

socket.on("connect_error", () => {
setTimeout(() => {
socket.connect();
}, 1000);
});
  • disconnect

This event is fired upon disconnection.

socket.on("disconnect", (reason) => {
// ...
});

Here is the list of possible reasons:

Reason Description
io server disconnect The server has forcefully disconnected the socket with socket.disconnect()
io client disconnect The socket was manually disconnected using socket.disconnect()
ping timeout The server did not respond in the pingTimeout range
transport close The connection was closed (example: the user has lost connection, or the network was changed from WiFi to 4G)
transport error The connection has encountered an error (example: the server was killed during a HTTP long-polling cycle)

Note: those events, along with disconnecting, newListener and removeListener, are special events that shouldn’t be used in your application:

// BAD, will throw an error
socket.emit("disconnect");
Caught a mistake? Edit this page on GitHub