diff --git a/src/ext/hx-upsert.js b/src/ext/hx-upsert.js
index 7579e36ff..ed20cd6fc 100644
--- a/src/ext/hx-upsert.js
+++ b/src/ext/hx-upsert.js
@@ -6,9 +6,10 @@
//
// Modifiers:
// key:attr - attribute name for sorting (default: id)
-// sort - sort ascending
+// sort - sort ascending (without sort, new elements are appended)
// sort:desc - sort descending
-// prepend - prepend elements without keys (default: append)
+// prepend - insert new elements at the start (when sorting, only
+// elements without a key are prepended)
//==========================================================
(() => {
let api;
@@ -37,6 +38,7 @@
handle_swap: (style, target, fragment, swapSpec) => {
if (style === 'upsert') {
let keyAttr = swapSpec.key || 'id';
+ let sorting = !!swapSpec.sort;
let desc = swapSpec.sort === 'desc';
let firstChild = target.firstChild;
@@ -58,7 +60,7 @@
}
let newKey = getKey(newEl);
- if (!newKey) {
+ if (!newKey || !sorting) {
if (swapSpec.prepend) {
target.insertBefore(newEl, firstChild);
} else {
diff --git a/test/tests/ext/hx-upsert.js b/test/tests/ext/hx-upsert.js
index c1ea8c2c2..65b87a1e6 100644
--- a/test/tests/ext/hx-upsert.js
+++ b/test/tests/ext/hx-upsert.js
@@ -241,5 +241,116 @@ describe('hx-upsert extension', function() {
assert.equal(list.children[1].id, 'item-1')
})
+ it('appends new keyed elements when sort is not set', async function () {
+ mockResponse('GET', '/test', '
New Item 2
Updated Item 3
New Item 4
')
+ let div = createProcessedHTML('Original Item 1
Original Item 3
');
+ div.click()
+ await htmx.timeout(20)
+ assert.equal(div.children.length, 4)
+ assert.equal(div.children[0].id, 'item-1')
+ assert.equal(div.children[0].textContent, 'Original Item 1')
+ assert.equal(div.children[1].id, 'item-3')
+ assert.equal(div.children[1].textContent, 'Updated Item 3')
+ assert.equal(div.children[2].id, 'item-2')
+ assert.equal(div.children[2].textContent, 'New Item 2')
+ assert.equal(div.children[3].id, 'item-4')
+ assert.equal(div.children[3].textContent, 'New Item 4')
+ })
+
+ it('prepends new keyed elements in response order when sort is not set', async function () {
+ mockResponse('GET', '/test', 'Four
Two
Updated 3
')
+ let div = createProcessedHTML('');
+ div.click()
+ await htmx.timeout(20)
+ assert.equal(div.children.length, 4)
+ assert.equal(div.children[0].id, 'item-4')
+ assert.equal(div.children[1].id, 'item-2')
+ assert.equal(div.children[2].id, 'item-1')
+ assert.equal(div.children[3].id, 'item-3')
+ assert.equal(div.children[3].textContent, 'Updated 3')
+ })
+
+ it('sorts new keyed elements ascending when sort is set', async function () {
+ mockResponse('GET', '/test', 'Four
Two
Updated 3
')
+ let div = createProcessedHTML('');
+ div.click()
+ await htmx.timeout(20)
+ assert.equal(div.children[0].id, 'item-1')
+ assert.equal(div.children[1].id, 'item-2')
+ assert.equal(div.children[2].id, 'item-3')
+ assert.equal(div.children[2].textContent, 'Updated 3')
+ assert.equal(div.children[3].id, 'item-4')
+ })
+
+ it('sorts new keyed elements descending when sort:desc is set', async function () {
+ mockResponse('GET', '/test', 'Two
Four
')
+ let div = createProcessedHTML('');
+ div.click()
+ await htmx.timeout(20)
+ assert.equal(div.children[0].id, 'item-4')
+ assert.equal(div.children[1].id, 'item-3')
+ assert.equal(div.children[2].id, 'item-2')
+ assert.equal(div.children[3].id, 'item-1')
+ })
+
+ it('hx-partial without sort appends new keyed elements', async function () {
+ mockResponse('GET', '/test', 'Two
Updated 3
')
+ let container = createProcessedHTML('');
+ container.click()
+ await htmx.timeout(20)
+ let list = container.querySelector('#list')
+ assert.equal(list.children[0].id, 'item-1')
+ assert.equal(list.children[1].id, 'item-3')
+ assert.equal(list.children[1].textContent, 'Updated 3')
+ assert.equal(list.children[2].id, 'item-2')
+ })
+
+ it('hx-partial with sort keeps ascending order', async function () {
+ mockResponse('GET', '/test', 'Four
Two
')
+ let container = createProcessedHTML('');
+ container.click()
+ await htmx.timeout(20)
+ let list = container.querySelector('#list')
+ assert.equal(list.children[0].id, 'item-1')
+ assert.equal(list.children[1].id, 'item-2')
+ assert.equal(list.children[2].id, 'item-3')
+ assert.equal(list.children[3].id, 'item-4')
+ })
+
+ it('hx-partial with sort:desc keeps descending order', async function () {
+ mockResponse('GET', '/test', 'Two
')
+ let container = createProcessedHTML('');
+ container.click()
+ await htmx.timeout(20)
+ let list = container.querySelector('#list')
+ assert.equal(list.children[0].id, 'item-3')
+ assert.equal(list.children[1].id, 'item-2')
+ assert.equal(list.children[2].id, 'item-1')
+ })
+
+ it('hx-upsert tag without sort appends new keyed elements', async function () {
+ mockResponse('GET', '/test', 'Two
Updated 3
')
+ let container = createProcessedHTML('');
+ container.click()
+ await htmx.timeout(20)
+ let list = container.querySelector('#list')
+ assert.equal(list.children[0].id, 'item-1')
+ assert.equal(list.children[1].id, 'item-3')
+ assert.equal(list.children[1].textContent, 'Updated 3')
+ assert.equal(list.children[2].id, 'item-2')
+ })
+
+ it('hx-upsert tag prepends new keyed elements when sort is not set', async function () {
+ mockResponse('GET', '/test', 'Four
Two
')
+ let container = createProcessedHTML('');
+ container.click()
+ await htmx.timeout(20)
+ let list = container.querySelector('#list')
+ assert.equal(list.children[0].id, 'item-4')
+ assert.equal(list.children[1].id, 'item-2')
+ assert.equal(list.children[2].id, 'item-1')
+ assert.equal(list.children[3].id, 'item-3')
+ })
+
})
diff --git a/www/src/content/extensions/08-hx-upsert.md b/www/src/content/extensions/08-hx-upsert.md
index d15cb296b..de34c00ee 100644
--- a/www/src/content/extensions/08-hx-upsert.md
+++ b/www/src/content/extensions/08-hx-upsert.md
@@ -52,14 +52,14 @@ The result will be:
The upsert swap style:
1. **Updates** elements with matching IDs (replaces their outerHTML)
-2. **Inserts** new elements that don't have matching IDs
+2. **Inserts** new elements that don't have matching IDs at the end of the target
3. **Preserves** existing elements not present in the response
## Configuration
### Sorting
-Add `sort` to maintain elements in ascending order by ID:
+New items are appended unless `sort` is set. Add `sort` to maintain elements in ascending order by ID:
```html
@@ -82,9 +82,9 @@ Use `key:attr` to sort by a different attribute:
```
-### Prepend Unkeyed Elements
+### Prepend
-By default, elements without IDs are appended. Use `prepend` to insert them at the beginning:
+By default, new elements are appended. Use `prepend` to insert them at the beginning, in the order they appear in the response. When `sort` is also set, keyed elements are placed by sort order and `prepend` only affects elements without a key:
```html