Client API

IO

Exposed as the io namespace in the standalone build, or the result of calling require('socket.io-client').

<script src="/socket.io/socket.io.js"></script><script>  const socket = io('http://localhost');</script>

const io = require('socket.io-client');// or with import syntaximport io from 'socket.io-client';

io.protocol

• (Number)

The protocol revision number (currently: 4).

The protocol defines the format of the packets exchanged between the client and the server. Both the client and the server must use the same revision in order to understand each other.

You can find more information here.

io([url][, options])

• url (String) (defaults to window.location)
• options (Object)
  • forceNew (Boolean) whether to reuse an existing connection
• Returns Socket

Creates a new Manager for the given URL, and attempts to reuse an existing Manager for subsequent calls, unless the multiplex option is passed with false. Passing this option is the equivalent of passing 'force new connection': true or forceNew: true.

A new Socket instance is returned for the namespace specified by the pathname in the URL, defaulting to /. For example, if the url is http://localhost/users, a transport connection will be established to http://localhost and a Socket.IO connection will be established to /users.

Query parameters can also be provided, either with the query option or directly in the url (example: http://localhost/users?token=abc).

const io = require("socket.io-client");const socket = io("ws://example.com/my-namespace", {  reconnectionDelayMax: 10000,  query: {    auth: "123"  }});

is the short version of:

const { Manager } = require("socket.io-client");const manager = new Manager("ws://example.com", {  reconnectionDelayMax: 10000});const socket = manager.socket("/my-namespace", {  query: {    auth: "123"  }});

See new Manager(url[, options]) for the list of available options.

Initialization examples

With multiplexing

By default, a single connection is used when connecting to different namespaces (to minimize resources):

const socket = io();const adminSocket = io('/admin');// a single connection will be established

That behaviour can be disabled with the forceNew option:

const socket = io();const adminSocket = io('/admin', { forceNew: true });// will create two distinct connections

Note: reusing the same namespace will also create two connections

const socket = io();const socket2 = io();// will also create two distinct connections

With custom path

const socket = io('http://localhost', {  path: '/myownpath'});// server-sideconst io = require('socket.io')({  path: '/myownpath'});

The request URLs will look like: localhost/myownpath/?EIO=3&transport=polling&sid=<id>

const socket = io('http://localhost/admin', {  path: '/mypath'});

Here, the socket connects to the admin namespace, with the custom path mypath.

The request URLs will look like: localhost/mypath/?EIO=3&transport=polling&sid=<id> (the namespace is sent as part of the payload).

With query parameters

const socket = io('http://localhost?token=abc');// server-sideconst io = require('socket.io')();// middlewareio.use((socket, next) => {  let token = socket.handshake.query.token;  if (isValid(token)) {    return next();  }  return next(new Error('authentication error'));});// thenio.on('connection', (socket) => {  let token = socket.handshake.query.token;  // ...});

With query option

const socket = io({  query: {    token: 'cde'  }});

The query content can also be updated on reconnection:

socket.on('reconnect_attempt', () => {  socket.io.opts.query = {    token: 'fgh'  }});

With extraHeaders

This only works if polling transport is enabled (which is the default). Custom headers will not be appended when using websocket as the transport. This happens because the WebSocket handshake does not honor custom headers. (For background see the WebSocket protocol RFC)

const socket = io({  transportOptions: {    polling: {      extraHeaders: {        'x-clientid': 'abc'      }    }  }});// server-sideconst io = require('socket.io')();// middlewareio.use((socket, next) => {  let clientId = socket.handshake.headers['x-clientid'];  if (isValid(clientId)) {    return next();  }  return next(new Error('authentication error'));});

With websocket transport only

By default, a long-polling connection is established first, then upgraded to “better” transports (like WebSocket). If you like to live dangerously, this part can be skipped:

const socket = io({  transports: ['websocket']});// on reconnection, reset the transports option, as the Websocket// connection may have failed (caused by proxy, firewall, browser, ...)socket.on('reconnect_attempt', () => {  socket.io.opts.transports = ['polling', 'websocket'];});

With a custom parser

The default parser promotes compatibility (support for Blob, File, binary check) at the expense of performance. A custom parser can be provided to match the needs of your application. Please see the example here.

const parser = require('socket.io-msgpack-parser'); // or require('socket.io-json-parser')const socket = io({  parser: parser});// the server-side must have the same parser, to be able to communicateconst io = require('socket.io')({  parser: parser});

With a self-signed certificate

// server-sideconst fs = require('fs');const server = require('https').createServer({  key: fs.readFileSync('server-key.pem'),  cert: fs.readFileSync('server-cert.pem')});const io = require('socket.io')(server);server.listen(3000);// client-sideconst socket = io({  // option 1  ca: fs.readFileSync('server-cert.pem'),  // option 2. WARNING: it leaves you vulnerable to MITM attacks!  rejectUnauthorized: false});

Manager

The Manager manages the Engine.IO client instance, which is the low-level engine that establishes the connection to the server (by using transports like WebSocket or HTTP long-polling).

The Manager handles the reconnection logic.

A single Manager can be used by several Sockets. You can find more information about this multiplexing feature here.

Please note that, in most cases, you won’t use the Manager directly but use the Socket instance instead.

new Manager(url[, options])

• url (String)
• options (Object)
• Returns Manager

Available options:

Available options for the underlying Engine.IO client:

Node.js-only options for the underlying Engine.IO client:

manager.reconnection([value])

• value (Boolean)
• Returns Manager|Boolean

Sets the reconnection option, or returns it if no parameters are passed.

manager.reconnectionAttempts([value])

• value (Number)
• Returns Manager|Number

Sets the reconnectionAttempts option, or returns it if no parameters are passed.

manager.reconnectionDelay([value])

• value (Number)
• Returns Manager|Number

Sets the reconnectionDelay option, or returns it if no parameters are passed.

manager.reconnectionDelayMax([value])

• value (Number)
• Returns Manager|Number

Sets the reconnectionDelayMax option, or returns it if no parameters are passed.

manager.timeout([value])

• value (Number)
• Returns Manager|Number

Sets the timeout option, or returns it if no parameters are passed.

manager.open([callback])

• callback (Function)
• Returns Manager

If the manager was initiated with autoConnect to false, launch a new connection attempt.

The callback argument is optional and will be called once the attempt fails/succeeds.

manager.connect([callback])

Synonym of manager.open([callback]).

manager.socket(nsp, options)

• nsp (String)
• options (Object)
• Returns Socket

Creates a new Socket for the given namespace.

Event: ‘connect_error’

• error (Object) error object

Fired upon a connection error.

Event: ‘connect_timeout’

Fired upon a connection timeout.

Event: ‘reconnect’

• attempt (Number) reconnection attempt number

Fired upon a successful reconnection.

Event: ‘reconnect_attempt’

• attempt (Number) reconnection attempt number

Fired upon an attempt to reconnect.

Event: ‘reconnecting’

• attempt (Number) reconnection attempt number

Fired upon an attempt to reconnect.

Event: ‘reconnect_error’

• error (Object) error object

Fired upon a reconnection attempt error.

Event: ‘reconnect_failed’

Fired when couldn’t reconnect within reconnectionAttempts.

Event: ‘ping’

Fired when a ping packet is written out to the server.

Event: ‘pong’

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

Fired when a pong is received from the server.

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); // undefinedsocket.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 argumentssocket.on('news', (arg1, arg2, arg3, arg4) => {  // ...});// with callbacksocket.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 reconnectionsocket.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) => {  // ...});