WebSocket: WebSocket() constructor

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

* Some parts of this feature may have varying levels of support.

Note: This feature is available in Web Workers.

The WebSocket() constructor returns a new WebSocket object and immediately attempts to establish a connection to the specified WebSocket 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:

js
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:".

js
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.

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

// Do something with socket

relativeWebSocket.close();

Specifications

Specification

WebSockets
# ref-for-dom-websocket-websocket①

Browser compatibility

Enable JavaScript to view this browser compatibility table.

Help improve MDN

Was this page helpful to you?

Yes No

Learn how to contribute

This page was last modified on Oct 30, 2025 by MDN contributors.

View this page on GitHub • Report a problem with this content

WebSocket: WebSocket() constructor

In this article

Syntax

Parameters

Exceptions

Examples

Specifications

Browser compatibility

See also

Help improve MDN