From 3ffa29723fd19870ee8a19632c001e1fb9aef469 Mon Sep 17 00:00:00 2001
From: Yogesh Singh Tilara <yogesht0311@gmail.com>
Date: Tue, 13 Jan 2026 20:56:22 +0530
Subject: [PATCH] Clarify OOB swaps with restricted sibling elements in
 Troublesome Tables docs

---
 www/content/docs.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/www/content/docs.md b/www/content/docs.md
index d8aaac86f..02b5fd136 100644
--- a/www/content/docs.md
+++ b/www/content/docs.md
@@ -622,6 +622,29 @@ To avoid this issue you can use a `template` tag to encapsulate these elements:
 </template>
 ```
 
+**Important:**  
+When performing out-of-band swaps, the *entire HTML response* (including both the main swap content and any OOB content) must be valid according to HTML placement rules.
+
+This means that even if the OOB element itself is valid, it may still need to be wrapped in a <template> when its sibling elements (including the main swap content) are restricted elements such as <tr>, <tbody>, or <li>. Browsers may otherwise rearrange or discard nodes during parsing, leading to unexpected swap behavior.
+
+For example, if the main swap content contains a `<tbody>` element, and an out-of-band swap targets a `<table>`, the OOB table must still be wrapped in a `<template>`:
+
+```html
+<tbody id="tablebody">
+  <tr><td>Test</td></tr>
+</tbody>
+
+<template>
+  <table id="myOobTable" hx-swap-oob="true">
+    <thead>
+      <tr><th>OOB header</th></tr>
+    </thead>
+    <tbody>
+      <tr><td>OOB row</td></tr>
+    </tbody>
+  </table>
+</template>
+
 #### Selecting Content To Swap
 
 If you want to select a subset of the response HTML to swap into the target, you can use the [hx-select](@/attributes/hx-select.md)