Reference
JS API: window.WPS
The plugin exposes window.WPS on all pages where the client script is loaded.
If you are building a WordPress block or script with a build tool, add
'wpsignal' as a dependency in your
wp_enqueue_script call to ensure WPS loads first.
Quick example
// Listen for a specific event
document.addEventListener('wpsignal:post.updated', (e) => {
console.log(e.detail.data.post_title);
});
// OR use the WPS API directly
const unsub = WPS.on('post.updated', (data, channel) => {
console.log('Post updated on', channel, data);
});
// Unsubscribe later
unsub();WPS.subscribe( channels )
Subscribe to additional channels on the shared connection.
| Parameter | Type |
|---|---|
| channels | string[] |
WPS.unsubscribe( channels )
Unsubscribe from channels.
| Parameter | Type |
|---|---|
| channels | string[] |
WPS.publish( channel, event, data? )
Publish a JSON message through the WebSocket. No-ops on SSE (one-way transport).
| Parameter | Type |
|---|---|
| channel | string |
| event | string |
| data? | Record< string, unknown > |
WPS.publishBinary( channel, data )
Send a raw binary frame to the server over the WebSocket. Frame format: 2-byte BE channel name length + channel bytes + payload. No-ops on SSE (one-way transport) or when not connected.
| Parameter | Type |
|---|---|
| channel | string |
| data | Uint8Array |
WPS.on( event, handler )
() => void Register a handler for a specific event name. Returns unsubscribe fn.
| Parameter | Type |
|---|---|
| event | string |
| handler | WPSEventHandler |
WPS.onMessage( handler )
() => void Register a catch-all handler for incoming JSON messages. Returns unsubscribe fn.
| Parameter | Type |
|---|---|
| handler | WPSMessageHandler |
WPS.onBinaryMessage( handler )
() => void Register a handler for incoming binary frames. Returns unsubscribe fn.
| Parameter | Type |
|---|---|
| handler | WPSBinaryHandler |
WPS.connected
readonly propertyboolean Whether the connection is currently open.
WPS.transport
readonly property'ws' | 'sse' | null Current transport layer, or null while still connecting.
WPS.onConnectionChange( handler )
() => void Register a callback for connection state changes. Returns unsubscribe fn.
| Parameter | Type |
|---|---|
| handler | ( connected: boolean ) => void |
Handler types
These types are used as parameters in the methods above.
WPSEventHandler
Used in WPS.on()
type WPSEventHandler = (
data: Record<string, unknown>,
channel: string
) => void;WPSMessageHandler
Used in WPS.onMessage()
type WPSMessageHandler = (
event: string,
data: Record<string, unknown>,
channel: string
) => void;WPSBinaryHandler
Used in WPS.onBinaryMessage(). For Yjs and other binary protocols.
type WPSBinaryHandler = (
channel: string,
data: Uint8Array
) => void;DOM CustomEvents
For every received message the client also dispatches a
CustomEvent on
document.
The event name is wpsignal:{event}.
Use these when you prefer the standard DOM event model.
document.addEventListener('wpsignal:post.updated', (e) => {
// e.detail = { event: 'post.updated', data: { ... }, channel: '...' }
console.log(e.detail.data);
});