WebSocket: close() method
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.
Note: This feature is available in Web Workers.
The WebSocket.close()
method closes the
WebSocket
connection or connection attempt, if any. If the connection is
already CLOSED
, this method does nothing.
Note: The process of closing the connection begins with a closing handshake, and the close()
method does not discard previously-sent messages before starting that closing handshake; even if the user agent is still busy sending those messages, the handshake will only start after the messages are sent.
Syntax
close()
close(code)
close(code, reason)
Parameters
code
Optional-
An integer WebSocket connection close code value indicating a reason for closure:
- If unspecified, a close code for the connection is automatically set: to
1000
for a normal closure, or otherwise to another standard value in the range1001
-1015
that indicates the actual reason the connection was closed. -
If specified, the value of this
code
parameter overrides the automatic setting of the close code for the connection, and instead sets a custom code. The value must be an integer: either1000
, or else a custom code of your choosing in the range3000
-4999
. If you specify acode
value, you should also specify areason
value.
- If unspecified, a close code for the connection is automatically set: to
reason
Optional-
A string providing a custom WebSocket connection close reason (a concise human-readable prose explanation for the closure). The value must be no longer than 123 bytes (encoded in UTF-8).
Note: Because UTF-8 uses two to four bytes to encode any non-ASCII characters, a 123-character
reason
value containing non-ASCII characters would exceed the 123-byte limit.If you specify a
reason
value, you should also specify acode
value.
Return value
None (undefined
).
Exceptions
InvalidAccessError
DOMException
-
Thrown if
code
is neither an integer equal to1000
nor an integer in the range3000
–4999
. SyntaxError
DOMException
-
Thrown if the UTF-8-encoded
reason
value is longer than 123 bytes.
Specifications
Specification |
---|
WebSockets Standard # ref-for-dom-websocket-close① |
Browser compatibility
BCD tables only load in the browser
See also
- RFC 6455 (the WebSocket Protocol specification)