feat(ws): handle non-JSON messages as raw HTML with cancelable event#3641
Merged
1cg merged 2 commits intobigskysoftware:fourfrom Jan 29, 2026
Merged
feat(ws): handle non-JSON messages as raw HTML with cancelable event#36411cg merged 2 commits intobigskysoftware:fourfrom
1cg merged 2 commits intobigskysoftware:fourfrom
Conversation
added 2 commits
January 29, 2026 20:31
Non-JSON WebSocket messages now swap as raw HTML instead of being dropped. Fires a cancelable htmx:ws:rawMessage event before swapping, allowing custom handling when needed. - If hx-target is set: swaps into target using element's swap style - If no hx-target: uses swap:none to protect connection element, but hx-partial tags in payload still reach their own targets - preventDefault() on the event skips default swap for custom handling Replaces the old htmx:wsUnknownMessage event which only notified but took no action on non-JSON data.
Tests cover: - Non-JSON messages swap as raw HTML into hx-target - swap:none used when no hx-target (protects connection element) - hx-partial tags in raw messages still reach their targets - htmx:ws:rawMessage event fires with message data - preventDefault() on rawMessage cancels default swap
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
When the WebSocket extension receives a non-JSON message (plain text/HTML), it now handles it gracefully instead of silently dropping it.
Behavior
hx-target: If the connection element hashx-target, raw HTML messages are swapped into that target usinghtmx.swap()hx-target→swap:none: Without an explicit target, raw messages useswap:noneto avoid accidentally overwriting the connection element's contents<hx-partial>still works: If the raw message contains<hx-partial>elements, they're extracted and processed normally (reaching their own targets) — even withouthx-targeton the connection elementhtmx:ws:rawMessageevent fires before any swap, withevent.detail.datacontaining the raw string. CallpreventDefault()to cancel the default swap behaviorWhy
This came up in discussion on #3638 — after switching to
htmx.swap(), raw HTML messages could inadvertently wipe the connection element's contents if nohx-targetwas set. This PR makes raw message handling explicit and safe.Tests
5 new tests covering all scenarios:
hx-targetswap:nonewhen nohx-target(protects connection element)<hx-partial>in raw messages still reaches targets withouthx-targethtmx:ws:rawMessageevent fires with datapreventDefault()cancels the default swapAll 59 WS extension tests passing.