From e17272ab77a54af5f6b5cff71a936e7cf1d72a16 Mon Sep 17 00:00:00 2001 From: James Barlow <332269+manwithacat@users.noreply.github.com> Date: Fri, 24 Apr 2026 12:55:03 +0100 Subject: [PATCH] docs: clarify next/previous selector scans whole DOM, not just siblings (#3430) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The parenthetical examples for `next ` and `previous ` described the result as the "closest following/previous sibling", but the actual behavior (correctly described in the surrounding sentence) is a forward/backward DOM scan that can match elements at any hierarchy level — not just siblings of the source element. Replaces "sibling" with "element" and adds a brief clarifying note in 10 places across 5 attribute and extension docs (hx-target, hx-trigger, hx-include, hx-disabled-elt, response-targets). No code change; only the parenthetical examples were misleading. Co-Authored-By: Claude Opus 4.7 (1M context) --- www/content/attributes/hx-disabled-elt.md | 4 ++-- www/content/attributes/hx-include.md | 4 ++-- www/content/attributes/hx-target.md | 4 ++-- www/content/attributes/hx-trigger.md | 4 ++-- www/content/extensions/response-targets.md | 4 ++-- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/www/content/attributes/hx-disabled-elt.md b/www/content/attributes/hx-disabled-elt.md index 3c6845bae..b68963662 100644 --- a/www/content/attributes/hx-disabled-elt.md +++ b/www/content/attributes/hx-disabled-elt.md @@ -16,10 +16,10 @@ added to them for the duration of the request. The value of this attribute can b * `find ` which will find the first child descendant element that matches the given CSS selector * `next` which resolves to [element.nextElementSibling](https://developer.mozilla.org/docs/Web/API/Element/nextElementSibling) * `next ` which will scan the DOM forward for the first element that matches the given CSS selector - (e.g. `next button` will disable the closest following sibling `button` element) + (e.g. `next button` will disable the closest following `button` element — note this scans the whole DOM forward, not just siblings) * `previous` which resolves to [element.previousElementSibling](https://developer.mozilla.org/docs/Web/API/Element/previousElementSibling) * `previous ` which will scan the DOM backwards for the first element that matches the given CSS selector. - (e.g. `previous input` will disable the closest previous sibling `input` element) + (e.g. `previous input` will disable the closest previous `input` element — note this scans the whole DOM backward, not just siblings) Here is an example with a button that will disable itself during a request: diff --git a/www/content/attributes/hx-include.md b/www/content/attributes/hx-include.md index bbedbbb6e..cb9ee1bf7 100644 --- a/www/content/attributes/hx-include.md +++ b/www/content/attributes/hx-include.md @@ -13,9 +13,9 @@ attribute can be: (e.g. `closest tr` will target the closest table row to the element). * `find ` which will find the first child descendant element that matches the given CSS selector. * `next ` which will scan the DOM forward for the first element that matches the given CSS selector. - (e.g. `next .error` will target the closest following sibling element with `error` class) + (e.g. `next .error` will target the next element with `error` class — note this scans the whole DOM forward, not just siblings) * `previous ` which will scan the DOM backwards for the first element that matches the given CSS selector. - (e.g. `previous .error` will target the closest previous sibling with `error` class) + (e.g. `previous .error` will target the previous element with `error` class — note this scans the whole DOM backward, not just siblings) Here is an example that includes a separate input value: diff --git a/www/content/attributes/hx-target.md b/www/content/attributes/hx-target.md index bca36b8a9..e4ec48de3 100644 --- a/www/content/attributes/hx-target.md +++ b/www/content/attributes/hx-target.md @@ -16,10 +16,10 @@ request. The value of this attribute can be: * `find ` which will find the first child descendant element that matches the given CSS selector. * `next` which resolves to [element.nextElementSibling](https://developer.mozilla.org/docs/Web/API/Element/nextElementSibling) * `next ` which will scan the DOM forward for the first element that matches the given CSS selector. - (e.g. `next .error` will target the closest following sibling element with `error` class) + (e.g. `next .error` will target the next element with `error` class — note this scans the whole DOM forward, not just siblings) * `previous` which resolves to [element.previousElementSibling](https://developer.mozilla.org/docs/Web/API/Element/previousElementSibling) * `previous ` which will scan the DOM backwards for the first element that matches the given CSS selector. - (e.g. `previous .error` will target the closest previous sibling with `error` class) + (e.g. `previous .error` will target the previous element with `error` class — note this scans the whole DOM backward, not just siblings) Here is an example that targets a div: diff --git a/www/content/attributes/hx-trigger.md b/www/content/attributes/hx-trigger.md index a2410f401..02e41064f 100644 --- a/www/content/attributes/hx-trigger.md +++ b/www/content/attributes/hx-trigger.md @@ -71,10 +71,10 @@ is seen again before the delay completes, it is ignored, the element will trigge * `find ` - finds the closest child matching the given css selector * `next` resolves to [element.nextElementSibling](https://developer.mozilla.org/docs/Web/API/Element/nextElementSibling) * `next ` scans the DOM forward for the first element that matches the given CSS selector. - (e.g. `next .error` will target the closest following sibling element with `error` class) + (e.g. `next .error` will target the next element with `error` class — note this scans the whole DOM forward, not just siblings) * `previous` resolves to [element.previousElementSibling](https://developer.mozilla.org/docs/Web/API/Element/previousElementSibling) * `previous ` scans the DOM backwards for the first element that matches the given CSS selector. - (e.g. `previous .error` will target the closest previous sibling with `error` class) + (e.g. `previous .error` will target the previous element with `error` class — note this scans the whole DOM backward, not just siblings) * `target:` - allows you to filter via a CSS selector on the target of the event. This can be useful when you want to listen for triggers from elements that might not be in the DOM at the point of initialization, by, for example, listening on the body, but with a target filter for a child element diff --git a/www/content/extensions/response-targets.md b/www/content/extensions/response-targets.md index e05abb795..fa1df5f7d 100644 --- a/www/content/extensions/response-targets.md +++ b/www/content/extensions/response-targets.md @@ -18,9 +18,9 @@ The value of each attribute can be: (e.g. `closest tr` will target the closest table row to the element). * `find ` which will find the first child descendant element that matches the given CSS selector. * `next ` which will scan the DOM forward for the first element that matches the given CSS selector. -(e.g. `next .error` will target the closest following sibling element with `error` class) +(e.g. `next .error` will target the next element with `error` class — note this scans the whole DOM forward, not just siblings) * `previous ` which will scan the DOM backwards for the first element that matches the given CSS selector. -(e.g `previous .error` will target the closest previous sibling with `error` class) +(e.g. `previous .error` will target the previous element with `error` class — note this scans the whole DOM backward, not just siblings) ## Installing