Skip to main content
Version: 4.x


A Namespace is a communication channel that allows you to split the logic of your application over a single shared connection (also called "multiplexing").

Namespace diagramNamespace diagram


Each namespace has its own:

io.of("/orders").on("connection", (socket) => {
socket.on("order:list", () => {});
socket.on("order:create", () => {});

io.of("/users").on("connection", (socket) => {
socket.on("user:list", () => {});
const orderNamespace = io.of("/orders");

orderNamespace.on("connection", (socket) => {

const userNamespace = io.of("/users");

userNamespace.on("connection", (socket) => {
socket.join("room1"); // distinct from the room in the "orders" namespace"room1").emit("holà");
const orderNamespace = io.of("/orders");

orderNamespace.use((socket, next) => {
// ensure the socket has access to the "orders" namespace, and then

const userNamespace = io.of("/users");

userNamespace.use((socket, next) => {
// ensure the socket has access to the "users" namespace, and then

Possible use cases:

  • you want to create a special namespace that only authorized users have access to, so the logic related to those users is separated from the rest of the application
const adminNamespace = io.of("/admin");

adminNamespace.use((socket, next) => {
// ensure the user has sufficient rights

adminNamespace.on("connection", socket => {
socket.on("delete user", () => {
// ...
  • your application has multiple tenants so you want to dynamically create one namespace per tenant
const workspaces = io.of(/^\/\w+$/);

workspaces.on("connection", socket => {
const workspace = socket.nsp;


Main namespace

Until now, you interacted with the main namespace, called /. The io instance inherits all of its methods:

io.on("connection", (socket) => {});
io.use((socket, next) => { next() });
// are actually equivalent to
io.of("/").on("connection", (socket) => {});
io.of("/").use((socket, next) => { next() });

Some tutorials may also mention io.sockets, it's simply an alias for io.of("/").

io.sockets === io.of("/")

Custom namespaces

To set up a custom namespace, you can call the of function on the server-side:

const nsp = io.of("/my-namespace");

nsp.on("connection", socket => {
console.log("someone connected");

nsp.emit("hi", "everyone!");

Client initialization

Same-origin version:

const socket = io(); // or io("/"), the main namespace
const orderSocket = io("/orders"); // the "orders" namespace
const userSocket = io("/users"); // the "users" namespace

Cross-origin/Node.js version:

const socket = io(""); // or io(""), the main namespace
const orderSocket = io(""); // the "orders" namespace
const userSocket = io(""); // the "users" namespace

In the example above, only one WebSocket connection will be established, and the packets will automatically be routed to the right namespace.

Please note that multiplexing will be disabled in the following cases:

  • multiple creation for the same namespace
const socket1 = io();
const socket2 = io(); // no multiplexing, two distinct WebSocket connections
  • different domains
const socket1 = io("");
const socket2 = io(""); // no multiplexing, two distinct WebSocket connections
const socket1 = io();
const socket2 = io("/admin", { forceNew: true }); // no multiplexing, two distinct WebSocket connections

Dynamic namespaces

It is also possible to dynamically create namespaces, either with a regular expression:


or with a function:

io.of((name, auth, next) => {
next(null, true); // or false, when the creation is denied

You can have access to the new namespace in the connection event:

io.of(/^\/dynamic-\d+$/).on("connection", (socket) => {
const namespace = socket.nsp;

The return value of the of() method is what we call the parent namespace, from which you can:

const parentNamespace = io.of(/^\/dynamic-\d+$/);

parentNamespace.use((socket, next) => { next() });

The middleware will automatically be registered on each child namespace.

const parentNamespace = io.of(/^\/dynamic-\d+$/);

parentNamespace.emit("hello"); // will be sent to users in /dynamic-1, /dynamic-2, ...

Existing namespaces have priority over dynamic namespaces. For example:

// register "dynamic-101" namespace

io.of(/^\/dynamic-\d+$/).on("connection", (socket) => {
// will not be called for a connection on the "dynamic-101" namespace

Complete API

The complete API exposed by the Namespace instance can be found here.