Client Initialization

    In the examples below, the io object comes either from:

    • the <script> import
    • NPM
    1. // ES6 import or TypeScript
      import { io } from "socket.io-client";
      // CommonJS
      const io = require("socket.io-client");

    If your front is served on the same domain as your server, you can simply use:

    1. const socket = io();

    The server URL will be deduced from the window.location object.

    In case your front is not served from the same domain as your server, you have to pass the URL of your server.

    1. const socket = io("https://server-domain.com");

    In that case, please make sure to enable on the server.

    Note: You can use either https or wss (respectively, http or ws).

    1. // the following forms are similar
      const socket = io("https://server-domain.com");
      const socket = io("wss://server-domain.com");
      const socket = io("server-domain.com"); // only in the browser when the page is served over https (will not work in Node.js)

    In the examples above, the client will connect to the main namespace. Using only the main namespace should be sufficient for most use cases, but you can specify the namespace with:

    1. // same origin version
      const socket = io("/admin");
      // cross origin version
      const socket = io("https://server-domain.com/admin");

    You can find more details about namespaces here.

    forceNew

    Default value: false

    Whether to create a new Manager instance.

    A Manager instance is in charge of the low-level connection to the server (established with HTTP long-polling or WebSocket). It handles the reconnection logic.

    A Socket instance is the interface which is used to sends events to — and receive events from — the server. It belongs to a given namespace.

    A single Manager can be attached to several Socket instances.

    The following example will reuse the same Manager instance for the 3 Socket instances (one single WebSocket connection):

    1. const socket = io("https://example.com"); // the main namespace
      const productSocket = io("https://example.com/product"); // the "product" namespace
      const orderSocket = io("https://example.com/order"); // the "order" namespace

    The following example will create 3 different Manager instances (and thus 3 distinct WebSocket connections):

    1. const socket = io("https://example.com"); // the main namespace
      const productSocket = io("https://example.com/product", { forceNew: true }); // the "product" namespace
      const orderSocket = io("https://example.com/order", { forceNew: true }); // the "order" namespace

    Reusing an existing namespace will also create a new Manager each time:

    1. const socket1 = io(); // 1st manager
      const socket2 = io(); // 2nd manager
      const socket3 = io("/admin"); // reuse the 1st manager
      const socket4 = io("/admin"); // 3rd manager

    multiplex

    Default value: true

    The opposite of forceNew: whether to reuse an existing Manager instance.

    Note: These settings will be shared by all Socket instances attached to the same Manager.

    transports

    Default value: ["polling", "websocket"]

    The low-level connection to the Socket.IO server can either be established with:

    • HTTP long-polling: successive HTTP requests (POST for writing, GET for reading)

    The following example disables the HTTP long-polling transport:

    Note: in that case, sticky sessions are not required on the server side (more information here).

    By default, the HTTP long-polling connection is established first, and then an upgrade to WebSocket is attempted (explanation ). You can use WebSocket first with:

    One possible downside is that the validity of your CORS configuration will only be checked if the WebSocket connection fails to be established.

    upgrade

    Default value: true

    Whether the client should try to upgrade the transport from HTTP long-polling to something better.

    rememberUpgrade

    Default value: 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.

    path

    Default value: /socket.io/

    It is the name of the path that is captured on the server side.

    The server and the client values must match (unless you are using a path-rewriting proxy in between):

    1. import { io } from "socket.io-client";

      const socket = io("https://example.com", {
      path: "/my-custom-path/"
      });

    Server

    1. const httpServer = require("http").createServer();
      const io = require("socket.io")(httpServer, {
      path: "/my-custom-path/"
      });

    Please note that this is different from the path in the URI, which represents the Namespace.

    Example:

    1. import { io } from "socket.io-client";

      const socket = io("https://example.com/order", {
      path: "/my-custom-path/"
      });
    • the Socket instance is attached to the “order” Namespace
    • the HTTP requests will look like: GET https://example.com/my-custom-path/?EIO=4&transport=polling&t=ML4jUwU

    query

    Default value: -

    Additional query parameters (then found in socket.handshake.query object on the server-side).

    Example:

    Client

    1. import { io } from "socket.io-client";

      const socket = io({
      query: {
      x: 42
      }
      });

    Server

    1. io.on("connection", (socket) => {
      console.log(socket.handshake.query); // prints { x: "42", EIO: "4", transport: "polling" }
      });

    The query parameters cannot be updated for the duration of the session, so changing the query on the client-side will only be effective when the current session gets closed and a new one is created:

    1. socket.io.on("reconnect_attempt", () => {
      socket.io.opts.query.x++;
      });

    Note: the following query parameters are reserved and can’t be used in your application:

    • transport: the transport name (“polling” or “websocket”)
    • sid: the session ID
    • j: if the transport is polling but a JSONP response is required
    • t: a hashed-timestamp used for cache-busting

    extraHeaders

    Default value: -

    Additional headers (then found in socket.handshake.headers object on the server-side).

    Example:

    Client

    1. import { io } from "socket.io-client";

      const socket = io({
      extraHeaders: {
      "my-custom-header": "1234"
      }
      });

    Server

    1. io.on("connection", (socket) => {
      console.log(socket.handshake.headers); // an object containing "my-custom-header": "1234"
      });

    A few notes:

    • this will not work when using only WebSocket in a browser
    1. import { io } from "socket.io-client";

      const socket = io({
      transports: ["websocket"],
      extraHeaders: {
      "my-custom-header": "1234" // WARN: this will be ignored in a browser
      }
      });

    This will work in Node.js or in React-Native though.

    • you can update the headers during a session, but it will not be reflected on the server-side (as the socket.handshake.headers object contains the headers that were sent during the Socket.IO handshake).

    withCredentials

    Default value: false

    Whether or not cross-site requests should made using credentials such as cookies, authorization headers or TLS client certificates. Setting withCredentials has no effect on same-site requests.

    1. import { io } from "socket.io-client";

      const socket = io({
      withCredentials: true
      });

    Documentation:

    forceBase64

    Default value: false

    Whether to force base64 encoding for binary content sent over WebSocket (always enabled for HTTP long-polling).

    timestampRequests

    Default value: true

    Whether to add the timestamp query param to each request (for cache busting).

    timestampParam

    Default value: "t"

    The name of the query parameter to use as our timestamp key.

    closeOnBeforeunload

    Added in v4.1.0

    Default value: true

    Whether to (silently) close the connection when the beforeunload event is emitted in the browser.

    With set to false, a disconnect event will be emitted by the Socket instance when the user reloads the page on Firefox (but not on Chrome or Safari).

    With closeOnBeforeunload set to true, all browsers will have the same behavior (no disconnect event when reloading the page). But this might cause issues if you use the beforeunload event in your application.

    Node.js-specific options

    The following options are supported:

    • agent
    • pfx
    • key
    • passphrase
    • cert
    • ca
    • ciphers
    • rejectUnauthorized

    Example with a self-signed certificate:

    • Client
    1. const fs = require("fs");
      const socket = require("socket.io-client")("https://example.com", {
      ca: fs.readFileSync("./cert.pem")
      });
    • Server
    1. const fs = require("fs");
      const server = require("https").createServer({
      cert: fs.readFileSync("./cert.pem"),
      key: fs.readFileSync("./key.pem")
      });
      const io = require("socket.io")(server);

    Example with client-certificate authentication:

    • Client
    1. const fs = require("fs");
      const socket = require("socket.io-client")("https://example.com", {
      ca: fs.readFileSync("./server-cert.pem"),
      cert: fs.readFileSync("./client-cert.pem"),
      key: fs.readFileSync("./client-key.pem"),
      });
    • Server
    1. const fs = require("fs");
      const server = require("https").createServer({
      cert: fs.readFileSync("./server-cert.pem"),
      key: fs.readFileSync("./server-key.pem"),
      requestCert: true,
      ca: [
      fs.readFileSync('client-cert.pem')
      ]
      });
      const io = require("socket.io")(server);

    Import note: rejectUnauthorized is a Node.js-only option, it will not bypass the security check in the browser:

    Note: These settings will be shared by all Socket instances attached to the same Manager.

    reconnection

    Default value: true

    Whether reconnection is enabled or not. If set to false, you need to manually reconnect:

    1. import { io } from "socket.io-client";

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

      const tryReconnect = () => {
      setTimeout(() => {
      socket.io.open((err) => {
      if (err) {
      tryReconnect();
      }
      });
      }, 2000);
      }

      socket.io.on("close", tryReconnect);

    reconnectionAttempts

    Default value: Infinity

    The number of reconnection attempts before giving up.

    reconnectionDelay

    Default value: 1000

    The initial delay before reconnection in milliseconds (affected by the value).

    reconnectionDelayMax

    Default value: 5000

    The maximum delay between two reconnection attempts. Each attempt increases the reconnection delay by 2x.

    randomizationFactor

    Default value: 0.5

    The randomization factor used when reconnecting (so that the clients do not reconnect at the exact same time after a server crash, for example).

    Example with the default values:

    • 1st reconnection attempt happens between 500 and 1500 ms (1000 * 2^0 * (<something between -0.5 and 1.5>))
    • 2nd reconnection attempt happens between 1000 and 3000 ms (1000 * 2^1 * (<something between -0.5 and 1.5>))
    • 3rd reconnection attempt happens between 2000 and 5000 ms (1000 * 2^2 * (<something between -0.5 and 1.5>))
    • next reconnection attempts happen after 5000 ms

    timeout

    Default value: 20000

    The timeout in milliseconds for each connection attempt.

    autoConnect

    Default value: true

    Whether to automatically connect upon creation. If set to false, you need to manually connect:

    1. import { io } from "socket.io-client";

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

      socket.connect();
      // or
      socket.io.open();

    parser

    Added in v2.2.0

    Default value: require("socket.io-parser")

    The parser used to marshall/unmarshall packets. Please see for more information.

    Note: These settings are specific to the given Socket instance.

    auth

    Added in v3.0.0

    Default value: -

    Credentials that are sent when accessing a namespace (see also ).

    Example:

    Client

    1. import { io } from "socket.io-client";

      const socket = io({
      auth: {
      token: "abcd"
      }
      });

    Server

    1. io.on("connection", (socket) => {
      console.log(socket.handshake.auth); // prints { token: "abcd" }
      });

    You can update the auth map when the access to the Namespace is denied:

    Or manually force the Socket instance to reconnect:

    1. socket.auth.token = "efgh";
      socket.disconnect().connect();