WebSocketInit

syntax

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

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

Shipping Chromium IDL (websocket_init.idl at trunk, 2026-09-20 — quoted verbatim):

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

the protocols member

the targetAddressSpace member (Chromium extension)

Chromium's dictionary declares a second member, targetAddressSpace (an IPAddressSpace: "public", "private", or "local"), gated behind its own LocalNetworkAccessWebSocketsTargetAddressSpace runtime flag in the flag registry. It mirrors fetch()'s option of the same name from the Local Network Access spec and is tracked as its own Chrome 154 feature, Support targetAddressSpace option for WebSockets — it is documented there, not here; this page records only that the extension point is already in use. It is not part of PR #76.

inputs

The dictionary is pure input: script constructs it and passes it to the constructor; nothing ever hands a WebSocketInit back to script. Unknown properties on the object are ignored per standard Web IDL dictionary conversion (only declared members are read), so a typo like { protocol: "soap" } silently offers no subprotocol rather than erroring — check socket.protocol after open if negotiation matters.

outputs

No direct output. The dictionary's observable effect is the offered-subprotocol set in the handshake and, after negotiation, the value of socket.protocol (the server's chosen subprotocol, or the empty string). The WPT tests assert exactly this: an empty bag connects successfully with no subprotocol, and { protocols: ['foobar', 'foobar2'] } yields ws.protocol === 'foobar' against an echo server that accepts the first offer.

errors

context and exposure

Available wherever the constructor is: Window and Worker contexts, when Chromium's WebSocketOptionBag runtime feature is enabled (flag record: status: "experimental", 2026-09-20). As a dictionary it has no prototype or global-object presence — there is nothing to feature-detect on window; detection goes through constructor behavior (see the overview).

lifecycle

The dictionary is read once, synchronously, during the constructor call (ParseOptionBag() in dom_websocket.cc copies protocols into the connection's protocol vector). Mutating the object afterwards has no effect on the connection; the object holds no live relationship to the socket. Future members (like targetAddressSpace) follow the same read-once model.

examples

// Correct: protocols is a sequence.
const ws = new WebSocket("wss://example.com/chat", {
  protocols: ["chat.v2", "chat.v1"],
});

ws.addEventListener("open", () => {
  if (ws.protocol === "") {
    // Server accepted the connection without choosing a subprotocol.
  }
});

// TypeError — a bare string is not a sequence:
// new WebSocket("wss://example.com/chat", { protocols: "chat.v2" });

// Silent no-op — unknown members are ignored (typo offers NO subprotocol):
// new WebSocket("wss://example.com/chat", { protocol: "chat.v2" });

browser compatibility

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

security and privacy

The dictionary grants no capability of its own: protocols feeds the same validated handshake header as the classic argument. Two considerations are real: the web-compat shift (objects stop throwing and start meaning “empty options” — under measurement on the spec PR), and the fact that future members carry their own security surface — the first, targetAddressSpace, exists precisely to integrate WebSockets with Local Network Access protections and is security-reviewed as its own feature.

see also

• Add options bag to WebSocket constructor — overview (feature page)
• WebSocket(url, protocolsOrOptions) — the constructor that consumes this dictionary
• whatwg/websockets issue #42 — the extensibility proposal this dictionary answers
• Chrome Platform Status — feature 5080055102439424
• Showcase — why a dictionary demo (HEAD-checked 200, 2026-09-20)