From a0ecacad4a88450b5978053a70bf258a3b37a3d9 Mon Sep 17 00:00:00 2001
From: MichaelWest22 <michael@latent.nz>
Date: Tue, 8 Sep 2026 12:56:14 +1200
Subject: [PATCH] Add hx-partial tag handling to v2

---
 src/htmx.js                          |  61 ++++++++-
 test/attributes/hx-partial.js        | 191 +++++++++++++++++++++++++++
 test/index.html                      |   1 +
 www/content/attributes/hx-partial.md | 166 +++++++++++++++++++++++
 www/content/docs.md                  |  22 +++
 www/content/events.md                |  55 ++++++++
 www/content/reference.md             |   5 +
 7 files changed, 499 insertions(+), 2 deletions(-)
 create mode 100644 test/attributes/hx-partial.js
 create mode 100644 www/content/attributes/hx-partial.md

diff --git a/src/htmx.js b/src/htmx.js
index 2ceca7436..1de9274cd 100644
--- a/src/htmx.js
+++ b/src/htmx.js
@@ -601,6 +601,8 @@ var htmx = (function() {
    * @returns {DocumentFragmentWithTitle}
    */
   function makeFragment(response) {
+    // convert <hx-*> custom tags to <template hx type="*"> so they survive HTML parsing
+    response = response.replace(/<hx-([a-z]+)((?:\s[^>]*)?)>/gi, '<template hx type="$1"$2>').replace(/<\/hx-[a-z]+>/gi, '</template>')
     // strip head tag to determine shape of response we are dealing with
     const responseWithNoHead = response.replace(/<head(\s[^>]*)?>[\s\S]*?<\/head>/i, '')
     const startTag = getStartTag(responseWithNoHead)
@@ -1841,6 +1843,54 @@ var htmx = (function() {
     }
   }
 
+  /**
+   * @param {DocumentFragment|ParentNode} fragment
+   * @param {HtmxSettleInfo} settleInfo
+   * @param {Element} sourceElement
+   * @returns {boolean}
+   */
+  function findAndSwapPartials(fragment, settleInfo, sourceElement) {
+    var hxTemplates = findAll(fragment, 'template[hx]')
+    forEach(hxTemplates, function(template) {
+      var type = getRawAttribute(template, 'type')
+      if (type === 'partial') {
+        var targetSelector = getAttributeValue(template, 'hx-target') ||
+          (template.id ? '#' + CSS.escape(template.id) : null)
+        if (targetSelector) {
+          var swapOverride = getAttributeValue(template, 'hx-swap')
+          var swapSpec = getSwapSpecification(template, swapOverride)
+          var targets = querySelectorAllExt(sourceElement || getDocument().body, targetSelector, false)
+          if (targets.length === 0) {
+            triggerErrorEvent(getDocument().body, 'htmx:partialErrorNoTarget', { template, targetSelector, sourceElement })
+          }
+          forEach(targets, function(target) {
+            target = asElement(target)
+            if (target) {
+              var fragment = template.content.cloneNode(true)
+              var beforeSwapDetails = { shouldSwap: true, target, fragment }
+              if (!triggerEvent(target, 'htmx:partialBeforeSwap', beforeSwapDetails)) return
+              target = beforeSwapDetails.target
+              if (beforeSwapDetails.shouldSwap) {
+                swap(target, beforeSwapDetails.fragment, swapSpec, {
+                  contextElement: target,
+                  afterSwapCallback: function() {
+                    forEach(settleInfo.elts, function(elt) {
+                      triggerEvent(elt, 'htmx:partialAfterSwap', beforeSwapDetails)
+                    })
+                  }
+                })
+              }
+            }
+          })
+        }
+      } else {
+        triggerEvent(getDocument().body, 'htmx:processTemplate', { type, template, settleInfo, sourceElement })
+      }
+      template.parentNode.removeChild(template)
+    })
+    return hxTemplates.length > 0
+  }
+
   /**
    * @param {DocumentFragment} fragment
    * @param {HtmxSettleInfo} settleInfo
@@ -1906,7 +1956,7 @@ var htmx = (function() {
         target.textContent = content
       // Otherwise, make the fragment and process it
       } else {
-        let fragment = makeFragment(content)
+        let fragment = typeof content === 'string' ? makeFragment(content) : content
 
         settleInfo.title = swapOptions.title || fragment.title
         if (swapOptions.historyRequest) {
@@ -1938,6 +1988,8 @@ var htmx = (function() {
             template.remove()
           }
         })
+        // partial swaps — after oob, before main swap
+        var hasPartials = findAndSwapPartials(fragment, settleInfo, swapOptions.contextElement || asElement(target))
 
         // normal swap
         if (swapOptions.select) {
@@ -1948,7 +2000,12 @@ var htmx = (function() {
           fragment = newFragment
         }
         handlePreservedElements(fragment)
-        swapWithStyle(swapSpec.swapStyle, swapOptions.contextElement, target, fragment, settleInfo)
+        // if the response contained only <hx-partial> tags and nothing else, skip the main swap
+        if (hasPartials && !fragment.childElementCount && !fragment.textContent.trim()) {
+          settleInfo.elts = [asElement(target)]
+        } else {
+          swapWithStyle(swapSpec.swapStyle, swapOptions.contextElement, target, fragment, settleInfo)
+        }
         restorePreservedElements()
       }
 
diff --git a/test/attributes/hx-partial.js b/test/attributes/hx-partial.js
new file mode 100644
index 000000000..19d81f7fb
--- /dev/null
+++ b/test/attributes/hx-partial.js
@@ -0,0 +1,191 @@
+describe('hx-partial', function() {
+  beforeEach(function() {
+    this.server = makeServer()
+    clearWorkArea()
+  })
+  afterEach(function() {
+    this.server.restore()
+    clearWorkArea()
+  })
+
+  it('swaps partial with explicit hx-target', function() {
+    this.server.respondWith('GET', '/test', "<hx-partial hx-target='#d1'>Partial</hx-partial>")
+    var div = make('<div hx-get="/test">click me</div>')
+    make('<div id="d1"></div>')
+    div.click()
+    this.server.respond()
+    byId('d1').innerHTML.should.equal('Partial')
+  })
+
+  it('swaps partial with custom swap style', function() {
+    this.server.respondWith('GET', '/test', "<hx-partial hx-target='#d1' hx-swap='beforeend'>Appended</hx-partial>")
+    make('<div id="d1">Existing</div>')
+    var div = make('<div hx-get="/test">click me</div>')
+    div.click()
+    this.server.respond()
+    byId('d1').innerHTML.should.equal('ExistingAppended')
+  })
+
+  it('swaps main target and partial target when both present', function() {
+    this.server.respondWith('GET', '/test', "<div>Main</div><hx-partial hx-target='#d2' hx-swap='innerHTML'><span>Partial</span></hx-partial>")
+    var div = make('<div hx-get="/test">click me</div>')
+    make('<div id="d2">Old</div>')
+    div.click()
+    this.server.respond()
+    div.innerHTML.should.equal('<div>Main</div>')
+    byId('d2').innerHTML.should.equal('<span>Partial</span>')
+  })
+
+  it('does not swap main target when response contains only partial', function() {
+    this.server.respondWith('GET', '/test', "<hx-partial hx-target='#d2'>Updated</hx-partial>")
+    var div = make('<div hx-get="/test">Original</div>')
+    make('<div id="d2">OOB</div>')
+    div.click()
+    this.server.respond()
+    div.innerHTML.should.equal('Original')
+    byId('d2').innerHTML.should.equal('Updated')
+  })
+
+  it('does not swap main target when only whitespace and partial present', function() {
+    this.server.respondWith('GET', '/test', "\n  <hx-partial hx-target='#d1'>Updated</hx-partial>  \n")
+    var div = make('<div hx-get="/test">Original</div>')
+    make('<div id="d1">Old</div>')
+    div.click()
+    this.server.respond()
+    div.innerHTML.should.equal('Original')
+    byId('d1').innerHTML.should.equal('Updated')
+  })
+
+  it('swaps both targets when empty element and partial present', function() {
+    this.server.respondWith('GET', '/test', "<p></p><hx-partial hx-target='#d1'>Updated</hx-partial>")
+    var div = make('<div hx-get="/test">Original</div>')
+    make('<div id="d1">Old</div>')
+    div.click()
+    this.server.respond()
+    div.querySelector('p').should.not.equal(null)
+    byId('d1').innerHTML.should.equal('Updated')
+  })
+
+  it('swaps both targets when plain text and partial present', function() {
+    this.server.respondWith('GET', '/test', "Hello<hx-partial hx-target='#d1'>Updated</hx-partial>")
+    var div = make('<div hx-get="/test">Original</div>')
+    make('<div id="d1">Old</div>')
+    div.click()
+    this.server.respond()
+    div.textContent.should.equal('Hello')
+    byId('d1').innerHTML.should.equal('Updated')
+  })
+
+  it('swaps partial to all elements matching a class selector', function() {
+    this.server.respondWith('GET', '/test', "<hx-partial hx-target='.target' hx-swap='innerHTML'>Updated</hx-partial>")
+    var div = make('<div hx-get="/test">click me</div>')
+    make('<div id="d1" class="target">A</div>')
+    make('<div id="d2" class="target">B</div>')
+    div.click()
+    this.server.respond()
+    byId('d1').innerHTML.should.equal('Updated')
+    byId('d2').innerHTML.should.equal('Updated')
+  })
+
+  it('resolves closest selector relative to triggering element', function() {
+    this.server.respondWith('GET', '/test', "<hx-partial hx-target='closest li' hx-swap='innerHTML'>Updated</hx-partial>")
+    var li = make('<ul><li id="item-1">Item 1 <button id="btn" hx-get="/test">Edit</button></li></ul>')
+    byId('btn').click()
+    this.server.respond()
+    byId('item-1').innerHTML.should.equal('Updated')
+  })
+
+  it('executes script in partial', function() {
+    window.testVar = 0
+    this.server.respondWith('GET', '/test', "<hx-partial hx-target='#d1'><script>window.testVar = 42<\/script></hx-partial>")
+    var div = make('<div hx-get="/test">click me</div>')
+    make('<div id="d1"></div>')
+    div.click()
+    this.server.respond()
+    window.testVar.should.equal(42)
+    delete window.testVar
+  })
+
+  it('template fallback form works identically', function() {
+    this.server.respondWith('GET', '/test', '<template hx type="partial" hx-target="#d1">Partial</template>')
+    var div = make('<div hx-get="/test">click me</div>')
+    make('<div id="d1"></div>')
+    div.click()
+    this.server.respond()
+    byId('d1').innerHTML.should.equal('Partial')
+  })
+
+  it('multiple partials in one response all execute', function() {
+    this.server.respondWith('GET', '/test',
+      "<hx-partial hx-target='#d1'>One</hx-partial><hx-partial hx-target='#d2'>Two</hx-partial>")
+    var div = make('<div hx-get="/test">click me</div>')
+    make('<div id="d1"></div>')
+    make('<div id="d2"></div>')
+    div.click()
+    this.server.respond()
+    byId('d1').innerHTML.should.equal('One')
+    byId('d2').innerHTML.should.equal('Two')
+  })
+
+  it('swaps partial using element id as implicit target', function() {
+    this.server.respondWith('GET', '/test', "<hx-partial id='d1'>ByID</hx-partial>")
+    var div = make('<div hx-get="/test">click me</div>')
+    make('<div id="d1"></div>')
+    div.click()
+    this.server.respond()
+    byId('d1').innerHTML.should.equal('ByID')
+  })
+
+  it('partial with no matching target does not throw', function() {
+    this.server.respondWith('GET', '/test', "<hx-partial hx-target='#nonexistent'>Content</hx-partial>")
+    var div = make('<div hx-get="/test">Original</div>')
+    div.click()
+    this.server.respond()
+    div.innerHTML.should.equal('Original')
+  })
+
+  it('swaps partial content independently to each matched target', function() {
+    this.server.respondWith('GET', '/test', "<hx-partial hx-target='.target' hx-swap='innerHTML'><b>Updated</b></hx-partial>")
+    var div = make('<div hx-get="/test">click me</div>')
+    make('<div id="d1" class="target">A</div>')
+    make('<div id="d2" class="target">B</div>')
+    make('<div id="d3" class="target">C</div>')
+    div.click()
+    this.server.respond()
+    byId('d1').innerHTML.should.equal('<b>Updated</b>')
+    byId('d2').innerHTML.should.equal('<b>Updated</b>')
+    byId('d3').innerHTML.should.equal('<b>Updated</b>')
+    // each target must have its own node, not the same shared reference
+    byId('d1').querySelector('b').should.not.equal(byId('d2').querySelector('b'))
+    byId('d2').querySelector('b').should.not.equal(byId('d3').querySelector('b'))
+  })
+
+  it('fires htmx:processTemplate for unknown hx-xxx tags allowing custom handling', function() {
+    this.server.respondWith('GET', '/test', "<hx-toast message='Hello'></hx-toast>")
+    var div = make('<div hx-get="/test">click me</div>')
+    make('<div id="d1"></div>')
+    var fired = false
+    var detail = null
+    var listener = htmx.on('htmx:processTemplate', function(evt) {
+      fired = true
+      detail = evt.detail
+      byId('d1').textContent = detail.template.getAttribute('message')
+    })
+    div.click()
+    this.server.respond()
+    fired.should.equal(true)
+    detail.type.should.equal('toast')
+    byId('d1').textContent.should.equal('Hello')
+    htmx.off('htmx:processTemplate', listener)
+  })
+
+  it('partial initializes htmx attributes in swapped content', function() {
+    this.server.respondWith('GET', '/test', "<hx-partial hx-target='#d1'><button id='btn2' hx-get='/other'>Go</button></hx-partial>")
+    var div = make('<div hx-get="/test">click me</div>')
+    make('<div id="d1"></div>')
+    div.click()
+    this.server.respond()
+    should.exist(byId('btn2'))
+    byId('btn2').getAttribute('hx-get').should.equal('/other')
+  })
+})
diff --git a/test/index.html b/test/index.html
index fb4473b0b..f14c1bdd1 100644
--- a/test/index.html
+++ b/test/index.html
@@ -94,6 +94,7 @@ <h2>Mocha Test Suite</h2>
 <script src="attributes/hx-disinherit.js"></script>
 <script src="attributes/hx-on-wildcard.js"></script>
 <script src="attributes/hx-params.js"></script>
+<script src="attributes/hx-partial.js"></script>
 <script src="attributes/hx-patch.js"></script>
 <script src="attributes/hx-post.js"></script>
 <script src="attributes/hx-preserve.js"></script>
diff --git a/www/content/attributes/hx-partial.md b/www/content/attributes/hx-partial.md
new file mode 100644
index 000000000..1b1e78702
--- /dev/null
+++ b/www/content/attributes/hx-partial.md
@@ -0,0 +1,166 @@
++++
+title = "hx-partial"
+description = """
+  hx-partial is a server-sent swap command. The server wraps content in <hx-partial hx-target="..."> \
+  tags in its response; htmx reads the targeting instructions, performs the swap, and discards the \
+  envelope — it is never inserted into the DOM."""
++++
+
+`<hx-partial>` is a **server-sent swap command**, not a DOM element. It exists only in the HTTP
+response body. The server wraps content in `<hx-partial hx-target="...">` tags to tell htmx
+where to swap that content; htmx reads the instructions, performs the swap, and discards the
+envelope entirely — nothing from the `<hx-partial>` tag itself ever appears in the page.
+
+This is similar to [`hx-swap-oob`](@/attributes/hx-swap-oob.md) but with key differences:
+the envelope is always consumed and discarded, targets are resolved relative to the **triggering
+element** using the full htmx extended selector vocabulary, and partials execute **before** the
+main swap.
+
+## Basic usage
+
+A response can contain any number of `<hx-partial>` elements alongside (or instead of) the
+main response content:
+
+```html
+<div>Updated main content</div>
+
+<hx-partial hx-target="#notifications">
+  3 new messages
+</hx-partial>
+
+<hx-partial hx-target="#user-status" hx-swap="outerHTML">
+  <span id="user-status" class="online">Online</span>
+</hx-partial>
+```
+
+The first `<hx-partial>` replaces the `innerHTML` of `#notifications`. The second replaces
+the entire `#user-status` element using `outerHTML`. The `<div>` is swapped into the main
+request target as normal.
+
+## id shorthand
+
+If you give the `<hx-partial>` an `id` attribute and omit `hx-target`, htmx uses `#<id>` as
+the target selector:
+
+```html
+<hx-partial id="alerts">
+  Saved successfully!
+</hx-partial>
+```
+
+This is equivalent to `<hx-partial hx-target="#alerts">`.
+
+## Controlling the swap style
+
+The `hx-swap` attribute on `<hx-partial>` accepts all the same values as
+[`hx-swap`](@/attributes/hx-swap.md) on a normal element. The default is `innerHTML`.
+
+```html
+<hx-partial hx-target="#feed" hx-swap="beforeend">
+  <li>New item</li>
+</hx-partial>
+```
+
+## Extended selectors
+
+`hx-target` on a partial is resolved relative to the **triggering element**, so you can use
+the full htmx extended selector vocabulary:
+
+```html
+<hx-partial hx-target="closest tr">
+  <td>Updated</td><td>values</td>
+</hx-partial>
+
+<hx-partial hx-target="find .status">
+  Active
+</hx-partial>
+```
+
+See [`hx-target`](@/attributes/hx-target.md) for the full list of extended selectors
+(`closest`, `find`, `next`, `previous`, etc.).
+
+## Multiple partials
+
+Any number of `<hx-partial>` elements may appear in a single response. They are processed in
+document order, all before the main swap.
+
+```html
+<hx-partial hx-target="#cart-count">2</hx-partial>
+<hx-partial hx-target="#cart-total">$19.98</hx-partial>
+<hx-partial hx-target="#last-added" hx-swap="afterbegin">
+  <li>Widget</li>
+</hx-partial>
+```
+
+## Partials-only response
+
+If the response contains **only** `<hx-partial>` elements (no other content), the main swap
+is suppressed and the original target is left unchanged. This lets the server update
+arbitrary parts of the page without touching the element that triggered the request.
+
+```html
+<!-- entire response — main target is not modified -->
+<hx-partial hx-target="#status">Done</hx-partial>
+<hx-partial hx-target="#count">42</hx-partial>
+```
+
+## Template fallback form
+
+If a partial response is accidentally rendered as a full page — for example during
+development or due to a server misconfiguration — raw `<hx-partial>` tags will appear
+as visible text in the browser. The `<template hx type="partial">` form avoids this:
+browsers treat `<template>` as inert and render nothing, so the page stays blank rather
+than leaking raw swap commands.
+
+```html
+<template hx type="partial" hx-target="#alerts">
+  Saved!
+</template>
+```
+
+Both forms behave identically when processed by htmx.
+
+## Troublesome tables and lists
+
+Before the response is parsed, htmx converts `<hx-partial>` tags into `<template>` elements.
+Because the content lives inside `template.content`, it is parsed in a fragment context and
+survives intact — `<tr>`, `<td>`, `<li>` and similar elements are preserved regardless of
+where the `<hx-partial>` appears in the response.
+
+```html
+<hx-partial hx-target="#row-3" hx-swap="outerHTML">
+  <tr id="row-3"><td>Updated</td></tr>
+</hx-partial>
+```
+
+If your template engine requires strictly valid HTML and rejects unknown tags, use the
+template fallback form with the appropriate wrapper so the parser sees valid content:
+
+```html
+<template hx type="partial" hx-target="find tbody" hx-swap="beforeend">
+  <table><tbody><tr><td>New row</td></tr></tbody></table>
+</template>
+```
+
+## Comparison with hx-swap-oob
+
+| | `hx-swap-oob` | `<hx-partial>` |
+|---|---|---|
+| Placed on | the content element itself | a wrapper element (always stripped) |
+| Target resolution | by `id` match or CSS selector | htmx extended selectors, relative to triggering element |
+| Execution order | before main swap | before main swap |
+| Template engine safe form | `<template>` wrapper | `<template hx type="partial">` |
+| Cancellable via event | `htmx:oobBeforeSwap` | `htmx:partialBeforeSwap` |
+
+## Events
+
+* [`htmx:partialBeforeSwap`](@/events.md#htmx:partialBeforeSwap) — fired before each partial swap; cancellable, allows re-targeting and fragment rewriting
+* [`htmx:partialAfterSwap`](@/events.md#htmx:partialAfterSwap) — fired after each partial swap
+* [`htmx:partialErrorNoTarget`](@/events.md#htmx:partialErrorNoTarget) — fired on `document.body` when no element matches the target selector
+* [`htmx:processTemplate`](@/events.md#htmx:processTemplate) — fired for any other `<hx-*>` tag type (e.g. `<hx-toast>`), allowing custom handling
+
+## Notes
+
+* `<hx-partial>` attributes are not inherited
+* Partials with no matching target are silently ignored (see `htmx:partialErrorNoTarget`)
+* `hx-swap-oob` and `<hx-partial>` can coexist in the same response without interfering
diff --git a/www/content/docs.md b/www/content/docs.md
index 6889666c0..f03ae91e8 100644
--- a/www/content/docs.md
+++ b/www/content/docs.md
@@ -25,6 +25,7 @@ custom_classes = "wide-content"
   * [synchronization](#synchronization)
   * [css transitions](#css_transitions)
   * [out of band swaps](#oob_swaps)
+  * [server-sent swap commands](#partial_swaps)
   * [parameters](#parameters)
   * [confirming](#confirming)
 * [inheritance](#inheritance)
@@ -622,6 +623,27 @@ To avoid this issue you can use a `template` tag to encapsulate these elements:
 </template>
 ```
 
+#### Server-Sent Partial Swap Commands {#partial_swaps}
+
+For more complex responses that need to update multiple parts of the page, htmx supports
+[`<hx-partial>`](@/attributes/hx-partial.md) — a server-sent swap command format. The server
+wraps content in `<hx-partial hx-target="...">` tags; htmx reads the targeting instructions,
+performs the swaps, and discards the envelope entirely. Nothing from the tag itself ever
+appears in the page.
+
+```html
+<div>Updated main content</div>
+
+<hx-partial hx-target="#cart-count">3</hx-partial>
+<hx-partial hx-target="#cart-total">$29.97</hx-partial>
+```
+
+Like `hx-swap-oob`, partials execute **before** the main swap and targets are resolved
+relative to the triggering element using the full [extended CSS selector](#extended-css-selectors)
+vocabulary (`closest`, `find`, `next`, `previous`, etc.).
+
+See the [`hx-partial` documentation](@/attributes/hx-partial.md) for full details.
+
 #### 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)
diff --git a/www/content/events.md b/www/content/events.md
index ebcc3309d..3539452eb 100644
--- a/www/content/events.md
+++ b/www/content/events.md
@@ -386,6 +386,37 @@ in the DOM to switch with.
 * `detail.content` - the element with the bad oob `id`
 * `detail.target` - the bad CSS selector
 
+### Event - `htmx:partialAfterSwap` {#htmx:partialAfterSwap}
+
+This event is triggered after a [`<hx-partial>`](@/attributes/hx-partial.md) element has been swapped into the DOM. It behaves identically to [`htmx:oobAfterSwap`](#htmx:oobAfterSwap).
+
+##### Details
+
+* `detail.elt` - the swapped in element
+* `detail.shouldSwap` - if the content was swapped (defaults to `true`)
+* `detail.target` - the target of the swap
+* `detail.fragment` - the response fragment
+
+### Event - `htmx:partialBeforeSwap` {#htmx:partialBeforeSwap}
+
+This event is triggered before a [`<hx-partial>`](@/attributes/hx-partial.md) element is swapped into the DOM. It behaves identically to [`htmx:oobBeforeSwap`](#htmx:oobBeforeSwap). Setting `detail.shouldSwap` to `false` cancels the swap. You may also reassign `detail.target` to redirect the swap to a different element, or replace `detail.fragment` to rewrite the content before it is inserted.
+
+##### Details
+
+* `detail.elt` - the target of the swap
+* `detail.shouldSwap` - if the content will be swapped (defaults to `true`)
+* `detail.target` - the target of the swap
+* `detail.fragment` - the response fragment (may be replaced to rewrite content)
+
+### Event - `htmx:partialErrorNoTarget` {#htmx:partialErrorNoTarget}
+
+This event is triggered on `document.body` when a [`<hx-partial>`](@/attributes/hx-partial.md) element's `hx-target` selector does not match any element in the current DOM.
+
+##### Details
+
+* `detail.content` - the partial template element with the unresolved target
+* `detail.target` - the CSS selector that could not be resolved
+
 ### Event - `htmx:onLoadError` {#htmx:onLoadError}
 
 This event is triggered when an error occurs during the `load` handling of an AJAX call
@@ -398,6 +429,30 @@ This event is triggered when an error occurs during the `load` handling of an AJ
 * `detail.exception` - the exception that occurred
 * `detail.requestConfig` - the configuration of the AJAX request
 
+### Event - `htmx:processTemplate` {#htmx:processTemplate}
+
+This event is triggered on `document.body` when a response contains an `<hx-*>` custom tag whose `type` attribute is **not** `partial` — for example `<hx-toast>`, `<hx-notification>`, etc. It gives application code (or extensions) a hook to handle custom `<hx-*>` element types.
+
+The template element still has its `.content` intact at the time the event fires. It is removed from the fragment immediately after the event returns.
+
+Here is an example that handles a custom `<hx-toast>` tag:
+
+```javascript
+const listener = htmx.on('htmx:processTemplate', function(evt) {
+  if (evt.detail.type === 'toast') {
+    showToast(evt.detail.template.getAttribute('message'))
+  }
+})
+// later: htmx.off('htmx:processTemplate', listener)
+```
+
+##### Details
+
+* `detail.type` - the tag type, i.e. the part after `hx-` (e.g. `"toast"` for `<hx-toast>`)
+* `detail.template` - the `<template>` element representing the custom tag, with `.content` intact
+* `detail.settleInfo` - the current settle info object
+* `detail.sourceElement` - the element that triggered the original request
+
 ### Event - `htmx:prompt` {#htmx:prompt}
 
 This event is triggered after a prompt has been shown to the user with the [`hx-prompt`](@/attributes/hx-prompt.md)
diff --git a/www/content/reference.md b/www/content/reference.md
index 8810b0b24..9c393ff7a 100644
--- a/www/content/reference.md
+++ b/www/content/reference.md
@@ -30,6 +30,7 @@ The most common attributes when using htmx.
 | [`hx-select-oob`](@/attributes/hx-select-oob.md) | select content to swap in from a response, somewhere other than the target (out of band)                           |
 | [`hx-swap`](@/attributes/hx-swap.md)             | controls how content will swap in (`outerHTML`, `beforeend`, `afterend`, ...)                                      |
 | [`hx-swap-oob`](@/attributes/hx-swap-oob.md)     | mark element to swap in from a response (out of band)                                                              |
+| [`hx-partial`](@/attributes/hx-partial.md)       | server-driven multi-target swap; wraps content to be swapped into one or more targets after the main swap          |
 | [`hx-target`](@/attributes/hx-target.md)         | specifies the target element to be swapped                                                                         |
 | [`hx-trigger`](@/attributes/hx-trigger.md)       | specifies the event that triggers the request                                                                      |
 | [`hx-vals`](@/attributes/hx-vals.md)             | add values to submit with the request (JSON format)                                                                |
@@ -158,6 +159,10 @@ All other attributes available in htmx.
 | [`htmx:oobAfterSwap`](@/events.md#htmx:oobAfterSwap)  | triggered after an out of band element as been swapped in
 | [`htmx:oobBeforeSwap`](@/events.md#htmx:oobBeforeSwap)  | triggered before an out of band element swap is done, allows you to configure the swap
 | [`htmx:oobErrorNoTarget`](@/events.md#htmx:oobErrorNoTarget)  | triggered when an out of band element does not have a matching ID in the current DOM
+| [`htmx:partialAfterSwap`](@/events.md#htmx:partialAfterSwap)  | triggered after an hx-partial element has been swapped in
+| [`htmx:partialBeforeSwap`](@/events.md#htmx:partialBeforeSwap)  | triggered before an hx-partial element swap is done, allows you to configure the swap
+| [`htmx:partialErrorNoTarget`](@/events.md#htmx:partialErrorNoTarget)  | triggered when an hx-partial element's target selector does not match any element in the DOM
+| [`htmx:processTemplate`](@/events.md#htmx:processTemplate)  | triggered when a response contains an unknown `<hx-*>` custom tag, allowing application code to handle it
 | [`htmx:prompt`](@/events.md#htmx:prompt)  | triggered after a prompt is shown
 | [`htmx:pushedIntoHistory`](@/events.md#htmx:pushedIntoHistory)  | triggered after a url is pushed into history
 | [`htmx:replacedInHistory`](@/events.md#htmx:replacedInHistory)  | triggered after a url is replaced in history