WebSocket: WebSocket() constructor

Syntax

new WebSocket(url)
new WebSocket(url, protocols)

Parameters

url

The URL of the target WebSocket server to connect to. The URL must use one of the following schemes: ws, wss, http, or https, and cannot include a URL fragment. If a relative URL is provided, it is relative to the base URL of the calling script.

protocols Optional

A single string or an array of strings representing the sub-protocol(s) that the client would like to use, in order of preference. If it is omitted, an empty array is used by default, i.e., [].

A single server can implement multiple WebSocket sub-protocols, and handle different types of interactions depending on the specified value. Note however that only one sub-protocol can be selected per connection.

The allowed values are those that can be specified in the Sec-WebSocket-Protocol HTTP header. These are values selected from the IANA WebSocket Subprotocol Name Registry, such as soap, wamp, ship and so on, or may be a custom name jointly understood by the client and the server.

Note: The connection is not established until the sub-protocol is negotiated with the server. The selected protocol can then be read from WebSocket.protocol: it will be the empty string if a connection cannot be established.

Exceptions

SyntaxError DOMException

Thrown if:

• parsing of url fails
• url has a scheme other than ws, wss, http, or https
• url has a fragment
• any of the values in protocols occur more than once, or otherwise fail to match the requirements for elements that comprise the value of Sec-WebSocket-Protocol fields as defined by the WebSocket Protocol specification

Examples

The examples below show how you might connect to a WebSocket.

The code below shows how we can connect to a socket using a URL with the wss scheme:

const wssWebSocket = new WebSocket("wss://websocket.example.org");
console.log(wssWebSocket.url); // 'wss://websocket.example.org'

// Do something with socket

wssWebSocket.close();

The code for connecting to an HTTPS URL is nearly the same. Under the hood the browser resolves this to a "WSS" connection, so the WebSocket.url will have the scheme "wss:".

const httpsWebSocket = new WebSocket("https://websocket.example.org");
console.log(httpsWebSocket.url); // 'wss://websocket.example.org'

// Do something with socket

httpsWebSocket.close();

We can also resolve relative URLs. The absolute URL will depend on the base URL of the context in which it is called.

relativeWebSocket = new WebSocket("/local/url");

// Do something with socket

relativeWebSocket.close();

Specifications

Browser compatibility

See also

• RFC 6455 (the WebSocket Protocol specification)