Socket

A Socket is the fundamental class for interacting with the server. A Socket belongs to a certain Namespace (by default /) and uses an underlying Manager to communicate.

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

socket.emit(‘hello’, { a: ‘b’, c: [] });

socket.on(‘hey’, (…args) => {
  // …
});

socket.id

• (String)

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.open()

• Returns Socket

Manually opens the socket.

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

// …
socket.open();

It can also be used to manually reconnect:

socket.on(‘disconnect’, () => {
  socket.open();
});

socket.connect()

Synonym of socket.open().

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

• args
• ack (Function)
• Returns Socket

Sends a message event. See socket.emit(eventName[, …args][, ack]).

socket.emit(eventName[, …args][, ack])

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

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

socket.emit(‘hello’, ‘world’);
socket.emit(‘with-binary’, 1, ‘2’, { 3: ‘4’, 5: Buffer.from([6, 7, 8]) });

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.

socket.on(‘news’, (data) => {
  console.log(data);
});

// with multiple arguments
socket.on(‘news’, (arg1, arg2, arg3, arg4) => {
  // …
});
// with callback
socket.on(‘news’, (cb) => {
  cb(0);
});

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

socket.compress(value)

• value (Boolean)
• Returns Socket

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.binary(value)

Specifies whether the emitted data contains binary. Increases performance when specified. Can be true or false.

socket.binary(false).emit(‘an event’, { some: ‘data’ });

socket.close()

• Returns Socket

Disconnects the socket manually.

socket.disconnect()

Synonym of socket.close().

Events

The Socket instance emits all events sent by its underlying Manager, which are related to the state of the connection to the server.

It also emits events related to the state of the connection to the Namespace:

• connect,
• disconnect
• error.

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 all cases but the first (disconnection by the server), the client will wait for a small random delay and then 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
});

Event: ‘error’

• error (Object) error object

Fired when an error occurs.

socket.on(‘error’, (error) => {
  // …
});

Event: ‘connect_error’

• error (Object) error object

Fired upon a connection error.

socket.on(‘connect_error’, (error) => {
  // …
});

Event: ‘connect_timeout’

Fired upon a connection timeout.

socket.on(‘connect_timeout’, (timeout) => {
  // …
});

Event: ‘reconnect’

• attempt (Number) reconnection attempt number

Fired upon a successful reconnection.

socket.on(‘reconnect’, (attemptNumber) => {
  // …
});

Event: ‘reconnect_attempt’

• attempt (Number) reconnection attempt number

Fired upon an attempt to reconnect.

socket.on(‘reconnect_attempt’, (attemptNumber) => {
  // …
});

Event: ‘reconnecting’

• attempt (Number) reconnection attempt number

Fired upon an attempt to reconnect.

socket.on(‘reconnecting’, (attemptNumber) => {
  // …
});

Event: ‘reconnect_error’

• error (Object) error object

Fired upon a reconnection attempt error.

socket.on(‘reconnect_error’, (error) => {
  // …
});

Event: ‘reconnect_failed’

Fired when the client couldn’t reconnect within reconnectionAttempts.

socket.on(‘reconnect_failed’, () => {
  // …
});

Event: ‘ping’

Fired when a ping is sent to the server.

socket.on(‘ping’, () => {
  // …
});

Event: ‘pong’

• ms (Number) number of ms elapsed since ping packet (i.e.: latency).

Fired when a pong is received from the server.

socket.on(‘pong’, (latency) => {
  // …
});

Caught a mistake? Edit this page on GitHub