A Socket is basically an which sends events to — and receive events from — the server over the network.

More information can be found here.

An unique identifier for the socket session. Set after the connect event is triggered, and updated after the reconnect event.

const socket = io("http://localhost");

console.log(socket.id); // undefined

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

socket.connected

• (Boolean)

Whether or not the socket is connected to the server.

const socket = io("http://localhost");

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

socket.disconnected

• (Boolean)

Whether or not the socket is disconnected from the server.

const socket = io("http://localhost");

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

socket.connect()

Added in v1.0.0

• Returns Socket

Manually connects the socket.

const socket = io({
  autoConnect: false
});

// ...
socket.connect();

It can also be used to manually reconnect:

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

socket.open()

Added in v1.0.0

Synonym of .

socket.send([…args][, ack])

• args
• ack (Function)
• Returns Socket

• eventName (String)
• args
• ack (Function)
• Returns

Emits an event to the socket identified by the string name. Any other parameters can be included. All serializable datastructures are supported, including Buffer.

The ack argument is optional and will be called with the server answer.

socket.emit("ferret", "tobi", (data) => {
  console.log(data); // data will be "woot"
});

// server:
//  io.on("connection", (socket) => {
//    socket.on("ferret", (name, fn) => {
//      fn("woot");
//    });
//  });

socket.on(eventName, callback)

• eventName (String)
• callback (Function)
• Returns Socket

Register a new handler for the given event.

The socket actually inherits every method of the Emitter class, like hasListeners, once or off (to remove an event listener).

socket.onAny(callback)

• callback (Function)

Register a new catch-all listener.

socket.onAny((event, ...args) => {
  console.log(`got ${event}`);
});

socket.prependAny(callback)

• callback (Function)

Register a new catch-all listener. The listener is added to the beginning of the listeners array.

socket.prependAny((event, ...args) => {
  console.log(`got ${event}`);
});

socket.offAny([listener])

• listener (Function)

Removes the previously registered listener. If no listener is provided, all catch-all listeners are removed.

const myListener = () => { /* ... */ };

socket.onAny(myListener);

// then, later
socket.offAny(myListener);

socket.offAny();

socket.listenersAny()

• Returns Function[]

Returns the list of registered catch-all listeners.

• value (Boolean)
• Returns

Sets a modifier for a subsequent event emission that the event data will only be compressed if the value is true. Defaults to true when you don’t call the method.

socket.compress(false).emit("an event", { some: "data" });

socket.disconnect()

Added in v1.0.0

• Returns Socket

Associated disconnection reason:

• client-side: "io client disconnect"
• server-side: "client namespace disconnect"

If this is the last active Socket instance of the Manager, the low-level connection will be closed.

socket.close()

Added in v1.0.0

Synonym of .

Flag: ‘volatile’

Added in v3.0.0

Sets a modifier for the subsequent event emission indicating that the packet may be dropped if:

• the socket is not connected
• the low-level transport is not writable (for example, when a POST request is already running in HTTP long-polling mode)

socket.volatile.emit(/* ... */); // the server may or may not receive it

Event: ‘connect’

Fired upon connection to the Namespace (including a successful reconnection).

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

// note: you should register event handlers outside of connect,
// so they are not registered again on reconnection
socket.on("myevent", () => {
  // ...
});

Event: ‘disconnect’

• reason (String)

Fired upon disconnection. The list of possible disconnection reasons:

In the first two cases (explicit disconnection), the client will not try to reconnect and you need to manually call socket.connect().

In all other cases, the client will wait for a small and then try to reconnect:

socket.on("disconnect", (reason) => {
  if (reason === "io server disconnect") {
    // the disconnection was initiated by the server, you need to reconnect manually
    socket.connect();
  }
  // else the socket will automatically try to reconnect
});

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

Caught a mistake? Edit this page on GitHub