Add options bag to WebSocket constructor

at a glance

why it exists

whatwg/websockets issue #42 (open since 2015) collects long-standing requests to make the WebSocket constructor extensible the way fetch() is: headers, cache mode, and other per-connection knobs have nowhere to go when the only extra parameter is a protocols list. The option bag itself doesn't add those capabilities — it adds the place for them. Chromium's immediate use is targetAddressSpace, needed so pages can opt WebSocket connections into Local Network Access checks the way fetch(url, { targetAddressSpace }) already can; that member is tracked as its own Chrome 154 feature (Support targetAddressSpace option for WebSockets) and rides on this extension point.

how the second argument is routed

The constructor's second parameter becomes the three-way union (DOMString or sequence<DOMString> or WebSocketInit). Which branch a value takes follows the Web IDL union conversion algorithm, so the routing is fully deterministic:

The spec PR's constructor step is a two-liner (quoted from the diff): “If protocolsOrOptions is a WebSocketInit dictionary, set protocols to protocolsOrOptions["protocols"]. Otherwise, set protocols to protocolsOrOptions.” Everything downstream — protocol validation, the opening handshake — is the existing algorithm.

In Chromium, dom_websocket.cc branches on RuntimeEnabledFeatures::WebSocketOptionBagEnabled(): with the flag on, the argument converts through the generated union V8UnionStringOrStringSequenceOrWebSocketInit and ParseConstructorOptionsWithBag() reads the dictionary; with the flag off, the pre-existing two-way union applies and an object coerces to a (rejected) protocol string. The declared IDL parameter is temporarily any so the two behaviors can coexist (websocket.idl, TODO note referencing crbug.com/542670554).

syntax

Proposed spec IDL (whatwg/websockets PR #76, open — quoted verbatim from the diff, 2026-09-20):

dictionary WebSocketInit {
  sequence<DOMString> protocols = [];
};

[Exposed=(Window,Worker)]
interface WebSocket : EventTarget {
  constructor(USVString url,
              optional (DOMString or sequence<DOMString> or WebSocketInit) protocolsOrOptions = []);
  // … rest of the interface unchanged
};

Shipping Chromium dictionary IDL (websocket_init.idl at trunk, 2026-09-20 — quoted verbatim, including the flag-gated Chromium extension):

dictionary WebSocketInit {
    sequence<DOMString> protocols = [];
    [RuntimeEnabled=LocalNetworkAccessWebSocketsTargetAddressSpace] IPAddressSpace targetAddressSpace;
};

The WebSocket living standard does not yet contain WebSocketInit (0 occurrences, verified 2026-09-20) — PR #76 must merge first. Full member documentation: the constructor overload and the WebSocketInit dictionary.

reference

• WebSocket(url, protocolsOrOptions) — the constructor overload: parameters, routing, errors, lifecycle
• WebSocketInit — the options dictionary and its protocols member

examples

Both spellings of the same connection — the classic positional form and the option bag:

// Classic (unchanged, works everywhere):
const a = new WebSocket("wss://example.com/chat", "soap");
const b = new WebSocket("wss://example.com/chat", ["soap", "wamp"]);

// Option bag (Chrome 154 behind the WebSocketOptionBag flag):
const c = new WebSocket("wss://example.com/chat", { protocols: ["soap"] });

// NOTE: the member is a sequence — a bare string throws a TypeError:
// new WebSocket("wss://example.com/chat", { protocols: "soap" });  // TypeError

Negotiation is unchanged: the server picks one offered subprotocol, and the chosen one appears on socket.protocol after open, exactly as with the positional forms.

browser compatibility

Interim table. BCD has no key for the option-bag overload (the WebSocket() constructor entry carries only the host constructor and the relative-URL subfeature, verified 2026-09-20), and webstatus.dev has no web-feature for it. Rows compiled from the linked primary sources.

For orientation, the host WebSocket() constructor itself is Baseline widely available (Chrome 5+, Edge 12+, Firefox 11+, Safari 5+ per BCD) — only the dictionary overload is new.

security and privacy

• No new network capability — the option bag changes how subprotocols are spelled, not what a page can connect to. The same protocol-validation and handshake algorithm of the living standard runs for every branch of the union.
• Web-compat, not security, is the open risk — code that today passes a non-iterable object (coerced to "[object Object]", then rejected with SyntaxError) would begin connecting with no subprotocols. The spec PR review flagged this pattern in shipping libraries and asked for usage measurement before merging; Chromium's flag gating (and the abandoned revert, CL 8294944) reflect the same caution.
• The extension point is where security options will land — Chromium's targetAddressSpace member (flag-gated in websocket_init.idl) exists to let pages opt in to Local Network Access restrictions for WebSocket connections to private networks; it is tracked as its own feature.

specifications

see also

• Chrome Platform Status — Add options bag to WebSocket constructor (API record)
• MDN — WebSocket() constructor (documents the classic two forms only; no WebSocketInit coverage, verified 2026-09-20)
• Chrome Platform Status — Support targetAddressSpace option for WebSockets (the first real option to ride this extension point)
• WPT — option-bag.any.js (the upstreamed tests)
• Chrome Platform Showcase — interactive demos for this feature