WebSocket Playground

The <WebSocketPlayground> component embeds a fully interactive WebSocket client inside your documentation. Readers can open connections, send messages, and observe responses in real time.

Live Demo#

Connect to a public WebSocket echo server — it sends back whatever you send:

With Subprotocols#

Usage in MDX#

MDX

<WebSocketPlayground
  url="wss://api.example.com/ws"
  title="Real-time Events"
  description="Subscribe to live events from the API."
  subprotocols={["events-v1"]}
  headers={{
    "X-Client-Version": "2.0"
  }}
  authType="bearer"
  servers={[
    { url: "wss://api.example.com/ws", description: "Production" },
    { url: "wss://staging.api.example.com/ws", description: "Staging" }
  ]}
/>

Features#

Live Connection

Real WebSocket connection with connect/disconnect controls and live status indicator.

Message History

Timestamped message log with color-coded sent, received, error, and system messages.

Subprotocols

Configure and negotiate WebSocket subprotocols.

Authentication

Supports Bearer token, API key, Basic auth, and custom headers.

Multiple Servers

Switch between server environments (production, staging, local).

Custom Headers

Add custom headers to the WebSocket handshake request.

Message Types#

Messages in the log are color-coded:

Type	Color	Description
SEND	Orange	Messages you send to the server
RECV	Blue	Messages received from the server
ERR	Red	Connection errors and protocol errors
SYS	Muted	Connect, disconnect, and status events

Testing JSON APIs#

For WebSocket APIs that use JSON messages, send structured messages like:

JSON

{ "type": "subscribe", "channel": "updates" }

JSON

{ "type": "message", "content": "Hello!", "room": "general" }

Props Reference#

Prop	Type	Required	Description
`url`	`string`	Yes	WebSocket URL (`ws://` or `wss://`).
`title`	`string`	No	Display title.
`description`	`string`	No	Description shown above the playground.
`subprotocols`	`string[]`	No	Pre-configured WebSocket subprotocols.
`headers`	`Record<string, string>`	No	Pre-populated handshake headers.
`authType`	`'bearer' \| 'apiKey' \| 'basic' \| 'none'`	No	Authentication method.
`servers`	`Array<{ url, description, protocol? }>`	No	Server environment options.

Was this page helpful?