Sponsors

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 syntax
import io from 'socket.io-client';

io.protocol

  • (Number)

The protocol revision number.

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

See new Manager(url[, options]) for the 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-side
const 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-side
const io = require('socket.io')();

// middleware
io.use((socket, next) => {
let token = socket.handshake.query.token;
if (isValid(token)) {
return next();
}
return next(new Error('authentication error'));
});

// then
io.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-side
const io = require('socket.io')();

// middleware
io.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 communicate
const io = require('socket.io')({
parser: parser
});

With a self-signed certificate

// server-side
const 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-side
const socket = io({
// option 1
ca: fs.readFileSync('server-cert.pem'),

// option 2. WARNING: it leaves you vulnerable to MITM attacks!
rejectUnauthorized: false
});

Manager

new Manager(url[, options])

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

Available options:

Option Default value Description
path /socket.io name of the path that is captured on the server side
reconnection true whether to reconnect automatically
reconnectionAttempts Infinity number of reconnection attempts before giving up
reconnectionDelay 1000 how long to initially wait before attempting a new reconnection (1000). Affected by +/- randomizationFactor, for example the default initial delay will be between 500 to 1500ms.
reconnectionDelayMax 5000 maximum amount of time to wait between reconnections (5000). Each attempt increases the reconnection delay by 2x along with a randomization as above
randomizationFactor 0.5 0 <= randomizationFactor <= 1
timeout 20000 connection timeout before a connect_error and connect_timeout events are emitted
autoConnect true by setting this false, you have to call manager.open whenever you decide it’s appropriate
query {} additional query parameters that are sent when connecting a namespace (then found in socket.handshake.query object on the server-side)
parser - the parser to use. Defaults to an instance of the Parser that ships with socket.io. See socket.io-parser.

Available options for the underlying Engine.IO client:

Option Default value Description
upgrade true whether the client should try to upgrade the transport from long-polling to something better.
forceJSONP false forces JSONP for polling transport.
jsonp true determines whether to use JSONP when necessary for polling. If disabled (by settings to false) an error will be emitted (saying “No transports available”) if no other transports are available. If another transport is available for opening a connection (e.g. WebSocket) that transport will be used instead.
forceBase64 false forces base 64 encoding for polling transport even when XHR2 responseType is available and WebSocket even if the used standard supports binary.
enablesXDR false enables XDomainRequest for IE8 to avoid loading bar flashing with click sound. default to false because XDomainRequest has a flaw of not sending cookie.
timestampRequests - whether to add the timestamp with each transport request. Note: polling requests are always stamped unless this option is explicitly set to false
timestampParam t the timestamp parameter
policyPort 843 port the policy server listens on
transports ['polling', 'websocket'] a list of transports to try (in order). Engine always attempts to connect directly with the first one, provided the feature detection test for it passes.
transportOptions {} hash of options, indexed by transport name, overriding the common options for the given transport
rememberUpgrade false If true and if the previous websocket connection to the server succeeded, the connection attempt will bypass the normal upgrade process and will initially try websocket. A connection attempt following a transport error will use the normal upgrade process. It is recommended you turn this on only when using SSL/TLS connections, or if you know that your network does not block websockets.
onlyBinaryUpgrades false whether transport upgrades should be restricted to transports supporting binary data
requestTimeout 0 timeout for xhr-polling requests in milliseconds (0) (only for polling transport)
protocols - a list of subprotocols (see MDN reference) (only for websocket transport)

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

Option Default value Description
agent false the http.Agent to use
pfx - Certificate, Private key and CA certificates to use for SSL.
key - Private key to use for SSL.
passphrase - A string of passphrase for the private key or pfx.
cert - Public x509 certificate to use.
ca - An authority certificate or array of authority certificates to check the remote host against.
ciphers - A string describing the ciphers to use or exclude. Consult the cipher format list for details on the format.
rejectUnauthorized false If true, the server certificate is verified against the list of supplied CAs. An ‘error’ event is emitted if verification fails. Verification happens at the connection level, before the HTTP request is sent.
perMessageDeflate true parameters of the WebSocket permessage-deflate extension (see ws module api docs). Set to false to disable.
extraHeaders {} Headers that will be passed for each request to the server (via xhr-polling and via websockets). These values then can be used during handshake or for special proxies.
forceNode false Uses NodeJS implementation for websockets - even if there is a native Browser-Websocket available, which is preferred by default over the NodeJS implementation. (This is useful when using hybrid platforms like nw.js or electron)
localAddress - the local IP address to connect to

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’

Fired upon an attempt to reconnect.

Event: ‘reconnecting’

  • attempt (Number) reconnection attempt number

Fired upon a successful reconnection.

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

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: new Buffer(6) });

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

Event: ‘connect’

Fired upon a connection 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: ‘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: ‘error’

  • error (Object) error object

Fired when an error occurs.

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

Event: ‘disconnect’

  • reason (String) either ‘io server disconnect’ or ‘io client disconnect’

Fired upon a disconnection.

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: ‘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 couldn’t reconnect within reconnectionAttempts.

socket.on('reconnect_failed', () => {
// ...
});

Event: ‘ping’

Fired when a ping packet is written out 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