WebSocket(url, protocols­OrOptions)

syntax

new WebSocket(url)
new WebSocket(url, protocols)        // string or array — classic form
new WebSocket(url, options)          // WebSocketInit dictionary — new

Proposed spec IDL (whatwg/websockets PR #76, quoted verbatim):

constructor(USVString url,
            optional (DOMString or sequence<DOMString> or WebSocketInit) protocolsOrOptions = []);

Shipping Chromium IDL (websocket.idl at trunk, 2026-09-20 — quoted verbatim; the parameter is temporarily any so behavior can differ by flag state):

// The type of `protocolsOrOptions` is `any` because the type needs to
// differ depending on the setting of the "WebSocketOptionBag" feature.
// TODO(crbug.com/542670554): Change to `(DOMString or sequence<DOMString> or
// WebSocketInit)` when the "WebSocketOptionBag" feature is permanently
// enabled and removed.
[CallWith=ExecutionContext, RaisesException]
constructor(USVString url, optional any protocolsOrOptions);

parameters

return value

A new WebSocket object in the CONNECTING state, exactly as the classic constructor returns; the connection is established asynchronously and open fires when the handshake (including subprotocol negotiation) completes. The server-selected subprotocol is then readable on socket.protocol. Which spelling supplied the protocols list is not observable on the returned object — { protocols: ["soap"] } and ["soap"] produce identical connections (in Chromium both feed the same Vector<String> handed to Connect() in dom_websocket.cc).

errors

context and exposure

Exposed wherever WebSocket is exposed: Window and Worker contexts ([Exposed=(Window,Worker)] in both the spec PR and Chromium's IDL). The overload requires no permission, secure-context, or policy gate of its own — only the WebSocketOptionBag runtime flag in Chromium. The dictionary branch simply does not exist when the flag is off; there is no partial state.

lifecycle

1. Script calls the constructor; the second argument is routed by union conversion (in Chromium: V8UnionStringOrStringSequenceOrWebSocketInit::Create, then ParseConstructorOptionsWithBag() in dom_websocket.cc).
2. A dictionary's protocols list replaces the positional list; all later steps are the classic algorithm: validate protocols, open the handshake, fire open/error/close.
3. The choice of spelling has no further lifecycle effect — reconnection, buffering, close(), and events behave identically.

examples

// Feature-detect, then prefer the extensible form:
let socket;
try {
  socket = new WebSocket("wss://example.com/feed", { protocols: ["v2.feed"] });
} catch {
  // Older engine: object was coerced to "[object Object]" → SyntaxError.
  socket = new WebSocket("wss://example.com/feed", ["v2.feed"]);
}

socket.addEventListener("open", () => {
  console.log("negotiated subprotocol:", socket.protocol); // "v2.feed" or ""
});

browser compatibility

Interim table. No BCD key for the overload (verified 2026-09-20); rows compiled from primary sources.

security and privacy

No new capability: the overload cannot reach any endpoint, port, or protocol the classic constructor cannot. The one behavioral delta is web-compat — a non-iterable object argument stops throwing SyntaxError and starts meaning “empty options”; the spec PR review is measuring how much shipping code relies on the old rejection before the change merges. Future dictionary members are individually security-reviewed (see targetAddressSpace on the WebSocketInit page).

see also

• Add options bag to WebSocket constructor — overview (feature page)
• WebSocketInit — the dictionary this overload accepts
• MDN — WebSocket() constructor (classic forms; no option-bag coverage, verified 2026-09-20)
• Chrome Platform Status — feature 5080055102439424
• Showcase — both argument forms demo (HEAD-checked 200, 2026-09-20)