@@ -1287,10 +1514,10 @@ describe('hx-ws WebSocket extension', function() {
let beforeDetail = null;
let afterDetail = null;
- container.addEventListener('htmx:before:ws:message', (e) => {
+ container.addEventListener('htmx:ws:before:message:incoming', (e) => {
beforeDetail = e.detail;
});
- container.addEventListener('htmx:after:ws:message', (e) => {
+ container.addEventListener('htmx:ws:after:message:incoming', (e) => {
afterDetail = e.detail;
});
@@ -1298,15 +1525,16 @@ describe('hx-ws WebSocket extension', function() {
ws.simulateRawMessage('
');
await htmx.timeout(20);
- assert.isNotNull(beforeDetail, 'before:ws:message should fire for raw messages');
- assert.isNull(beforeDetail.message.json, 'message.json should be null for raw data');
- assert.isString(beforeDetail.message.text, 'message.text should be present');
+ assert.isNotNull(beforeDetail, 'ws:before:message:incoming should fire for raw messages');
+ assert.equal(beforeDetail.message.type, 'text');
+ assert.equal(beforeDetail.message.data, '
');
+ assert.equal(await beforeDetail.message.text(), beforeDetail.message.data);
- assert.isNotNull(afterDetail, 'after:ws:message should fire for raw messages');
- assert.isNull(afterDetail.message.json, 'message.json should be null in after event too');
+ assert.isNotNull(afterDetail, 'ws:after:message:incoming should fire for raw messages');
+ assert.strictEqual(afterDetail.message, beforeDetail.message);
});
- it('JSON messages go through before/after:ws:message with message object', async function() {
+ it('JSON messages go through incoming message events', async function() {
let container = createProcessedHTML(`
@@ -1315,7 +1543,7 @@ describe('hx-ws WebSocket extension', function() {
await htmx.timeout(50);
let beforeDetail = null;
- container.addEventListener('htmx:before:ws:message', (e) => {
+ container.addEventListener('htmx:ws:before:message:incoming', (e) => {
beforeDetail = e.detail;
});
@@ -1325,9 +1553,9 @@ describe('hx-ws WebSocket extension', function() {
});
await htmx.timeout(20);
- assert.isNotNull(beforeDetail, 'before:ws:message should fire');
- assert.isNotNull(beforeDetail.message.json, 'message.json should be set for JSON messages');
- assert.isDefined(beforeDetail.message.json.content, 'message.json should have content field');
+ assert.isNotNull(beforeDetail, 'ws:before:message:incoming should fire');
+ let json = await beforeDetail.message.json();
+ assert.isDefined(json.content, 'message.json() should parse the message');
});
it('passes protocols to WebSocket constructor', async function() {
htmx.config.ws = { protocols: 'my-protocol' };
@@ -1376,13 +1604,13 @@ describe('hx-ws WebSocket extension', function() {
describe('Event Emission', function() {
- it('emits htmx:before:ws:connection before connection', async function() {
+ it('emits htmx:ws:before:connection before connection', async function() {
let beforeFired = false;
let attempt = null;
let container = document.createElement('div');
container.innerHTML = '
';
- container.addEventListener('htmx:before:ws:connection', (e) => {
+ container.addEventListener('htmx:ws:before:connection', (e) => {
beforeFired = true;
attempt = e.detail.connection.attempt;
});
@@ -1396,12 +1624,12 @@ describe('hx-ws WebSocket extension', function() {
container.remove();
});
- it('emits htmx:after:ws:connection after connection', async function() {
+ it('emits htmx:ws:after:connection after connection', async function() {
let afterFired = false;
let container = document.createElement('div');
container.innerHTML = '
';
- container.addEventListener('htmx:after:ws:connection', () => {
+ container.addEventListener('htmx:ws:after:connection', () => {
afterFired = true;
});
@@ -1413,11 +1641,11 @@ describe('hx-ws WebSocket extension', function() {
container.remove();
});
- it('can cancel initial connection via htmx:before:ws:connection', async function() {
+ it('can cancel initial connection via htmx:ws:before:connection', async function() {
let container = document.createElement('div');
container.innerHTML = '
';
- container.addEventListener('htmx:before:ws:connection', (e) => {
+ container.addEventListener('htmx:ws:before:connection', (e) => {
e.detail.connection.cancelled = true;
});
@@ -1429,14 +1657,14 @@ describe('hx-ws WebSocket extension', function() {
container.remove();
});
- it('can cancel reconnection via htmx:before:ws:connection', async function() {
+ it('can cancel reconnection via htmx:ws:before:connection', async function() {
htmx.config.ws = { reconnect: true, reconnectDelay: 50 };
let container = createProcessedHTML(`
`);
- container.addEventListener('htmx:before:ws:connection', (e) => {
+ container.addEventListener('htmx:ws:before:connection', (e) => {
if (e.detail.connection.attempt > 0) {
e.detail.connection.cancelled = true;
}
@@ -1444,13 +1672,13 @@ describe('hx-ws WebSocket extension', function() {
await htmx.timeout(50);
let firstWs = mockWebSocketInstances[0];
- firstWs.close();
+ firstWs.close(1006);
await htmx.timeout(150);
assert.equal(mockWebSocketInstances.length, 1, 'Should not reconnect when cancelled');
});
- it('emits htmx:before:ws:request before sending', async function() {
+ it('emits htmx:ws:before:message:outgoing before sending', async function() {
let beforeFired = false;
let div = createProcessedHTML(`
@@ -1458,7 +1686,7 @@ describe('hx-ws WebSocket extension', function() {
`);
- div.addEventListener('htmx:before:ws:request', () => {
+ div.addEventListener('htmx:ws:before:message:outgoing', () => {
beforeFired = true;
});
@@ -1469,34 +1697,37 @@ describe('hx-ws WebSocket extension', function() {
assert.isTrue(beforeFired);
});
- it('emits htmx:after:ws:request after sending', async function() {
- let afterFired = false;
+ it('emits htmx:ws:after:message:outgoing after sending', async function() {
+ let afterMessage;
let div = createProcessedHTML(`
`);
- div.addEventListener('htmx:after:ws:request', () => {
- afterFired = true;
+ div.addEventListener('htmx:ws:after:message:outgoing', (event) => {
+ afterMessage = event.detail.message;
});
await htmx.timeout(50);
div.querySelector('button').click();
await htmx.timeout(20);
- assert.isTrue(afterFired);
+ assert.isString(afterMessage.data);
+ assert.deepEqual(JSON.parse(afterMessage.data), {
+ headers: afterMessage.headers
+ });
});
- it('allows modifying message via htmx:before:ws:request', async function() {
+ it('allows modifying message via htmx:ws:before:message:outgoing', async function() {
let div = createProcessedHTML(`
`);
- div.addEventListener('htmx:before:ws:request', (e) => {
- e.detail.body.custom = 'added';
+ div.addEventListener('htmx:ws:before:message:outgoing', (e) => {
+ e.detail.message.values.custom = 'added';
});
await htmx.timeout(50);
@@ -1505,17 +1736,92 @@ describe('hx-ws WebSocket extension', function() {
let ws = mockWebSocketInstances[0];
let sent = JSON.parse(ws.lastSent);
- assert.equal(sent.body.custom, 'added');
+ assert.equal(sent.custom, 'added');
});
- it('can cancel send via htmx:before:ws:request', async function() {
+ it('waits for async authorization before sending', async function() {
let div = createProcessedHTML(`
`);
+ let resolveToken;
+ let token = new Promise(resolve => resolveToken = resolve);
+
+ div.addEventListener('htmx:ws:before:message:outgoing', (event) => {
+ event.detail.waitUntil(token.then(value => {
+ event.detail.message.headers.Authorization = `Bearer ${value}`;
+ }));
+ });
- div.addEventListener('htmx:before:ws:request', (e) => {
+ await htmx.timeout(50);
+ div.querySelector('button').click();
+ await htmx.timeout(5);
+
+ let ws = mockWebSocketInstances[0];
+ assert.isUndefined(ws.lastSent);
+
+ resolveToken('abc123');
+ await htmx.timeout(10);
+ assert.equal(JSON.parse(ws.lastSent).headers.Authorization, 'Bearer abc123');
+ });
+
+ it('sends outgoing messages in trigger order', async function() {
+ let div = createProcessedHTML(`
+
+
+
+ `);
+ let messageNumber = 0;
+
+ div.addEventListener('htmx:ws:before:message:outgoing', (event) => {
+ event.detail.message.values.messageNumber = ++messageNumber;
+ if (messageNumber === 1) event.detail.waitUntil(htmx.timeout(30));
+ });
+
+ await htmx.timeout(50);
+ let button = div.querySelector('button');
+ button.click();
+ button.click();
+ await htmx.timeout(60);
+
+ let sent = mockWebSocketInstances[0].sentMessages.map(JSON.parse);
+ assert.deepEqual(sent.map(message => message.messageNumber), [1, 2]);
+ });
+
+ it('sends replacement WebSocket data', async function() {
+ let div = createProcessedHTML(`
+
+
+
+ `);
+ let data = new Uint8Array([1, 2, 3]);
+ let afterMessage;
+
+ div.addEventListener('htmx:ws:before:message:outgoing', (event) => {
+ event.detail.message.data = data;
+ });
+ div.addEventListener('htmx:ws:after:message:outgoing', (event) => {
+ afterMessage = event.detail.message;
+ });
+
+ await htmx.timeout(50);
+ div.querySelector('button').click();
+ await htmx.timeout(20);
+
+ let ws = mockWebSocketInstances[0];
+ assert.strictEqual(ws.lastSent, data);
+ assert.strictEqual(afterMessage.data, data);
+ });
+
+ it('can cancel send via htmx:ws:before:message:outgoing', async function() {
+ let div = createProcessedHTML(`
+
+
+
+ `);
+
+ div.addEventListener('htmx:ws:before:message:outgoing', (e) => {
e.preventDefault();
});
@@ -1734,6 +2040,57 @@ describe('hx-ws WebSocket extension', function() {
assert.include(content.innerHTML, 'Item 1');
assert.include(content.innerHTML, 'Item 2');
});
+
+ // Incoming HTML uses inherited hx-select before the main swap.
+ it('uses element hx-select', async function() {
+ let container = createProcessedHTML(`
+
+ `);
+ await htmx.timeout(50);
+
+ let ws = mockWebSocketInstances[0];
+ ws.simulateRawMessage('
Selected
');
+ await htmx.timeout(20);
+
+ assert.equal(document.getElementById('content').innerHTML, '
Selected
');
+ });
+
+ // A JSON select overrides inherited hx-select for one incoming message.
+ it('message select overrides element hx-select', async function() {
+ let container = createProcessedHTML(`
+
+ `);
+ await htmx.timeout(50);
+
+ let ws = mockWebSocketInstances[0];
+ ws.simulateMessage({
+ content: '
Default
Override
',
+ select: '.override'
+ });
+ await htmx.timeout(20);
+
+ assert.equal(document.getElementById('content').innerHTML, '
Override
');
+ });
+
+ // Incoming HTML uses inherited hx-select-oob for client-selected OOB updates.
+ it('uses element hx-select-oob', async function() {
+ let container = createProcessedHTML(`
+
Original
+
Waiting
+ `);
+ await htmx.timeout(50);
+
+ let ws = mockWebSocketInstances[0];
+ ws.simulateRawMessage('
Connected
');
+ await htmx.timeout(20);
+
+ assert.equal(document.getElementById('ws-conn').textContent, 'Original');
+ assert.equal(document.getElementById('status').textContent, 'Connected');
+ });
it('message target overrides element hx-target', async function() {
let container = createProcessedHTML(`
@@ -1782,7 +2139,7 @@ describe('hx-ws WebSocket extension', function() {
describe('Bug Regressions', function() {
- it('htmx:after:ws:connection reports correct attempt number on reconnect', async function() {
+ it('htmx:ws:after:connection reports correct attempt number on reconnect', async function() {
htmx.config.ws = { reconnect: true, reconnectDelay: 50, reconnectJitter: 0 };
let container = createProcessedHTML(`
@@ -1791,20 +2148,20 @@ describe('hx-ws WebSocket extension', function() {
await htmx.timeout(50);
let reportedAttempt = null;
- container.addEventListener('htmx:after:ws:connection', (e) => {
+ container.addEventListener('htmx:ws:after:connection', (e) => {
reportedAttempt = e.detail.connection.attempt;
});
// Close to trigger reconnect
let ws = mockWebSocketInstances[0];
- ws.close();
+ ws.close(1006);
await htmx.timeout(150);
assert.isNotNull(reportedAttempt, 'after:ws:connection should have fired on reconnect');
assert.equal(reportedAttempt, 1, 'Reconnection attempt should be 1, not 0');
});
- it('htmx:before:ws:message includes raw data string', async function() {
+ it('htmx:ws:before:message:incoming includes raw data string', async function() {
let container = createProcessedHTML(`
@@ -1812,20 +2169,18 @@ describe('hx-ws WebSocket extension', function() {
`);
await htmx.timeout(50);
- let receivedData = null;
let receivedMessage = null;
- container.addEventListener('htmx:before:ws:message', (e) => {
- receivedData = e.detail.message.text;
- receivedMessage = e.detail.message.json;
+ container.addEventListener('htmx:ws:before:message:incoming', async (e) => {
+ receivedMessage = e.detail.message;
});
let ws = mockWebSocketInstances[0];
ws.simulateMessage({ content: '
Hello
' });
await htmx.timeout(20);
- assert.isString(receivedData, 'text should be the raw string');
- assert.isNotNull(receivedMessage, 'json should be the parsed JSON');
- assert.equal(receivedMessage.content, '
Hello
');
+ assert.equal(receivedMessage.data, JSON.stringify({ content: '
Hello
' }));
+ assert.equal(await receivedMessage.text(), receivedMessage.data);
+ assert.equal((await receivedMessage.json()).content, '
Hello
');
});
});
@@ -1851,10 +2206,12 @@ describe('hx-ws WebSocket extension', function() {
assert.isTrue(registry.has('/ws/test'), 'Connection should be in registry');
// Swap out the ws-host element entirely (simulates hx-swap replacing it)
+ let target = document.getElementById('outer');
await htmx.swap({
text: '
Replaced — no hx-ws:connect
',
- target: document.getElementById('outer'),
- swap: 'innerHTML'
+ target,
+ swap: 'innerHTML',
+ sourceElement: target
});
await htmx.timeout(50);
@@ -1929,14 +2286,16 @@ describe('hx-ws WebSocket extension', function() {
let registry = htmx.ext.ws.getRegistry();
// Close to trigger reconnect scheduling
- ws.close();
+ ws.close(1006);
await htmx.timeout(20);
// Remove element during the reconnect delay
+ let target = document.getElementById('outer');
await htmx.swap({
text: '
No more WS
',
- target: document.getElementById('outer'),
- swap: 'innerHTML'
+ target,
+ swap: 'innerHTML',
+ sourceElement: target
});
await htmx.timeout(250);
@@ -2047,53 +2406,7 @@ describe('hx-ws WebSocket extension', function() {
});
// ========================================
- // 14. RECONNECT JITTER BOOLEAN COMPAT (POLISH)
- // ========================================
-
- describe('reconnectJitter Boolean Compatibility', function() {
-
- it('treats reconnectJitter: true as 0.3 (default jitter)', async function() {
- htmx.config.ws = {
- reconnect: true,
- reconnectDelay: 50,
- reconnectJitter: true
- };
-
- let container = createProcessedHTML(`
-
- `);
- await htmx.timeout(50);
-
- // Should reconnect without breaking (true * delay would give NaN-like behavior)
- let ws = mockWebSocketInstances[0];
- ws.close();
- await htmx.timeout(150);
-
- assert.isTrue(mockWebSocketInstances.length > 1, 'Should reconnect with boolean jitter=true');
- });
-
- it('treats reconnectJitter: false as 0 (no jitter)', async function() {
- htmx.config.ws = {
- reconnect: true,
- reconnectDelay: 50,
- reconnectJitter: false
- };
-
- let container = createProcessedHTML(`
-
- `);
- await htmx.timeout(50);
-
- let ws = mockWebSocketInstances[0];
- ws.close();
- await htmx.timeout(100);
-
- assert.isTrue(mockWebSocketInstances.length > 1, 'Should reconnect with boolean jitter=false');
- });
- });
-
- // ========================================
- // 15. ADDITIONAL FINDINGS — DEEP REVIEW
+ // 14. ADDITIONAL FINDINGS — DEEP REVIEW
// ========================================
describe('Deep Review Fixes', function() {
@@ -2115,25 +2428,23 @@ describe('hx-ws WebSocket extension', function() {
let ws = mockWebSocketInstances[0];
let sent = JSON.parse(ws.lastSent);
- let requestId = sent.headers['HX-Request-ID'];
+ let messageId = sent.headers['HX-Message-ID'];
- // Remove the form that sent the request (simulates swap replacing the form)
+ // Remove the form that sent the message (simulates swap replacing the form)
form.remove();
await htmx.timeout(20);
- // Server responds with the request ID — should fall back to live connect element
+ // Server sends the message ID — should fall back to live connect element
ws.simulateMessage({
content: '
Response',
- 'HX-Request-ID': requestId
+ headers: { 'HX-Message-ID': messageId }
});
await htmx.timeout(20);
assert.include(document.getElementById('result').innerHTML, 'Response');
});
- it('cleans up expired pending requests on message receive', async function() {
- htmx.config.ws = { pendingRequestTTL: 50 };
-
+ it('cleans up expired pending messages on message receive', async function() {
let container = createProcessedHTML(`
@@ -2148,16 +2459,14 @@ describe('hx-ws WebSocket extension', function() {
let ws = mockWebSocketInstances[0];
let registry = htmx.ext.ws.getRegistry();
let conn = registry.get('/ws/test');
- assert.equal(conn.pendingRequests.size, 1, 'Should have 1 pending request');
-
- // Wait for TTL to expire
- await htmx.timeout(100);
+ assert.equal(conn.pendingMessages.size, 1, 'Should have 1 pending message');
+ conn.pendingMessages.values().next().value.timestamp -= 30001;
// Receive any message — should trigger cleanup
ws.simulateMessage({ type: 'ping' });
await htmx.timeout(20);
- assert.equal(conn.pendingRequests.size, 0, 'Expired pending request should be cleaned up');
+ assert.equal(conn.pendingMessages.size, 0, 'Expired pending message should be cleaned up');
});
it('closeConnection aborts the AbortController', async function() {
@@ -2175,11 +2484,8 @@ describe('hx-ws WebSocket extension', function() {
let ac = conn.abortController;
// Remove the element to trigger closeConnection
- await htmx.swap({
- text: '',
- target: document.getElementById('outer'),
- swap: 'innerHTML'
- });
+ let target = document.getElementById('outer');
+ await htmx.swap({ text: '', target, swap: 'innerHTML', sourceElement: target });
await htmx.timeout(50);
assert.isTrue(ac.signal.aborted, 'AbortController should be aborted on close');
diff --git a/www/src/content/extensions/03-hx-ws.md b/www/src/content/extensions/03-hx-ws.md
index d853bae09..f7ffb7dd3 100644
--- a/www/src/content/extensions/03-hx-ws.md
+++ b/www/src/content/extensions/03-hx-ws.md
@@ -24,7 +24,7 @@ If you used [`ws`](https://htmx.org/extensions/ws/) in htmx 2.0, see [migration
Open a [persistent](#wsreconnect) WebSocket connection:
```html
-
+
...
```
@@ -38,18 +38,16 @@ The browser receives this WebSocket message:
The result is:
```html
-
+
```
-The explicit target enables the normal swap. htmx uses:
+htmx uses the same rules as with a `text/html` response:
- [`hx-target="this"`](/reference/attributes/hx-target#this)
- [`hx-swap="innerHTML"`](/reference/attributes/hx-swap#innerhtml) (from [`htmx.config.defaultSwap`](/reference/config/htmx-config-defaultSwap))
-Without an element or JSON target, plain incoming HTML uses `swap:none`. Explicit [`hx-swap-oob`](/reference/attributes/hx-swap-oob) and [`
`](/reference/tags/hx-partial) swaps still run.
-
**Choose the Swap**
Use [`hx-swap`](/reference/attributes/hx-swap) and [`hx-target`](/reference/attributes/hx-target) to choose how and where updates swap:
@@ -88,12 +86,17 @@ The result is:
```
+You can also use:
+
+- [`hx-select`](/reference/attributes/hx-select) to select content for the swap
+- [`hx-select-oob`](/reference/attributes/hx-select-oob) to select more elements to swap
+
### Update Elements
-Use explicit extra swaps to update several elements:
+Start with the page elements to update:
```html
-
+
Old
@@ -101,7 +104,7 @@ Use explicit extra swaps to update several elements:
Offline
```
-The server sends an [`hx-swap-oob`](/reference/attributes/hx-swap-oob) element and an [`
`](/reference/tags/hx-partial):
+We’ll send an [`hx-swap-oob`](/reference/attributes/hx-swap-oob) element and an [``](/reference/tags/hx-partial) (new in 4.0):
```html
@@ -116,7 +119,7 @@ The server sends an [`hx-swap-oob`](/reference/attributes/hx-swap-oob) element a
The page becomes:
```html
-
+
Old
@@ -125,20 +128,48 @@ The page becomes:
Online
```
-`hx-swap="none"` disables the connection element's normal swap. The explicit extra swaps still run.
+
+Why wasn't the normal swap used?
+
+After htmx extracts extra swaps, the normal swap may be empty:
+
+```text
+(empty)
+```
+
+[`hx-swap-oob`](/reference/attributes/hx-swap-oob) and [``](/reference/tags/hx-partial) elements are extracted before the normal swap. By default, [`swapEmpty:false`](/reference/attributes/hx-swap#swapempty) leaves the connection unchanged.
+
+The server can also mix these updates with ordinary HTML:
+
+```html
+New chat content
+
+
+Busy
+```
+
+The first element uses the connection's target and swap. The partial updates `#status`.
+
+To disable the connection's swap, set `hx-swap="none"`:
+
+```html
+
+ ...
+
+```
+
+[`hx-swap-oob`](/reference/attributes/hx-swap-oob) and [``](/reference/tags/hx-partial) swaps still run.
+
+
### Send a Message
-Add [`hx-ws:send`](#hx-wssend) to a form inside the connection:
+Add [`hx-ws:send`](#hx-wssend) to an input inside the connection:
```html
```
@@ -148,19 +179,17 @@ The outgoing message is:
{
"headers": {
"HX-Request": "true",
- "HX-Request-ID": "550e8400-e29b-41d4-a716-446655440000",
+ "HX-Message-ID": "550e8400-e29b-41d4-a716-446655440000",
"HX-Request-Type": "partial",
- "HX-Source": "form",
+ "HX-Source": "input",
"HX-Target": "div#messages",
"HX-Current-URL": "https://example.com/chat"
},
- "body": {
- "message": "Hello"
- }
+ "message": "Hello"
}
```
-`headers` contains htmx metadata. `body` contains form values and [`hx-vals`](/reference/attributes/hx-vals).
+`headers` is reserved for metadata. Form values and `hx-vals` use the other top-level keys.
Repeat a form field to send an array:
@@ -172,16 +201,16 @@ Repeat a form field to send an array:
```
+The outgoing message is:
+
```jsonc
{
"headers": { /* ... */ },
- "body": {
- "tag": ["urgent", "public"]
- }
+ "tag": ["urgent", "public"]
}
```
-`hx-vals` overrides form values without coercing its types:
+[`hx-vals`](/reference/attributes/hx-vals) overrides form values without coercing its types:
```html