From 0298b69a48707012ca6e1050cb44690b7caa6a4d Mon Sep 17 00:00:00 2001 From: Pascal Baljet Date: Thu, 25 Sep 2025 17:47:12 +0200 Subject: [PATCH 1/9] Update merging-props.jsx --- resources/js/Pages/merging-props.jsx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/resources/js/Pages/merging-props.jsx b/resources/js/Pages/merging-props.jsx index 7b641706..36310ee4 100644 --- a/resources/js/Pages/merging-props.jsx +++ b/resources/js/Pages/merging-props.jsx @@ -18,8 +18,12 @@ export default function () {

Merging props

By default, Inertia overwrites props with the same name when reloading a page. However, there are instances, - such as pagination or infinite scrolling, where that is not the desired behavior. In these cases, you can merge - props instead of overwriting them. + such as pagination, where that is not the desired behavior. In these cases, you can merge props + instead of overwriting them. +

+

+ Prop merging only works during partial reloads. Full page visits will always + replace props entirely, even if you've marked them for merging.

Server side

From 45b090fdbfdcfaba2d0529cfe4e00afe69ffb468 Mon Sep 17 00:00:00 2001 From: Pascal Baljet Date: Thu, 25 Sep 2025 17:57:12 +0200 Subject: [PATCH 2/9] Update merging-props.jsx --- resources/js/Pages/merging-props.jsx | 66 ++++++++++++++++++++++++++-- 1 file changed, 63 insertions(+), 3 deletions(-) diff --git a/resources/js/Pages/merging-props.jsx b/resources/js/Pages/merging-props.jsx index 36310ee4..267ca814 100644 --- a/resources/js/Pages/merging-props.jsx +++ b/resources/js/Pages/merging-props.jsx @@ -6,6 +6,7 @@ export const meta = { links: [ { url: '#top', name: 'Introduction' }, { url: '#server-side', name: 'Server side' }, + { url: '#fine-grained-control', name: 'Fine-grained control' }, { url: '#client-side', name: 'Client side' }, { url: '#combining-with-deferred-props', name: 'Deferred props' }, { url: '#resetting-props', name: 'Resetting props' }, @@ -31,8 +32,8 @@ export default function () { the prop value.

- Use merge when merging simple arrays, and deepMerge when working with nested objects - that contain arrays or complex structures, such as pagination objects. + Use merge when you want to merge at the root level or specific properties, and{' '} + deepMerge when you want to recursively merge nested objects that contain arrays.

During the merging process, if the value is an array, the incoming items will be{' '} - appended to the existing array, not merged by index. However, you may chain the{' '} + appended to the existing array by default, not merged by index. You can change this behavior + and gain more precise control using the methods described in the{' '} + fine-grained control section. You may also chain the{' '} matchOn method to determine how existing items should be matched and updated.

You may also pass an array of keys to matchOn to specify multiple keys for matching. + +

Fine-grained control

+

+ For more precise control over merging, you can use the append() and prepend() methods. + By default, Inertia::merge() appends at the root level. You can change this behavior or target + specific nested properties. +

+ prepend(); + + // Target specific nested properties + Inertia::merge(User::paginate())->append('data'); + `} + /> +

+ You can also use prepend() to add items to the beginning of arrays, useful for chat messages + or activity feeds where newer items appear first. +

+

+ Both methods can be chained together and support the matchOn parameter for item matching. +

+ append('users', matchOn: 'username') + ->prepend('messages'); + `} + /> +

+ You can pass arrays to target multiple properties at once. +

+ append(['notifications', 'activities']); + `} + /> +

+ For advanced scenarios, pass a key-value array where the key is the property path and the value + is the matchOn field. +

+ append([ + 'users.data' => 'id', + 'messages' => 'uuid', + ]); + `} + />

Client side

On the client side, Inertia detects that this prop should be merged. If the prop returns an array, it will From fef0fbb660a0e0c2eb67e1155a9d17b977ea08c2 Mon Sep 17 00:00:00 2001 From: Pascal Baljet Date: Thu, 25 Sep 2025 18:08:37 +0200 Subject: [PATCH 3/9] Update merging-props.jsx --- resources/js/Pages/merging-props.jsx | 175 ++++++++++++--------------- 1 file changed, 78 insertions(+), 97 deletions(-) diff --git a/resources/js/Pages/merging-props.jsx b/resources/js/Pages/merging-props.jsx index 267ca814..c5d47ab7 100644 --- a/resources/js/Pages/merging-props.jsx +++ b/resources/js/Pages/merging-props.jsx @@ -6,7 +6,6 @@ export const meta = { links: [ { url: '#top', name: 'Introduction' }, { url: '#server-side', name: 'Server side' }, - { url: '#fine-grained-control', name: 'Fine-grained control' }, { url: '#client-side', name: 'Client side' }, { url: '#combining-with-deferred-props', name: 'Deferred props' }, { url: '#resetting-props', name: 'Resetting props' }, @@ -19,8 +18,8 @@ export default function () {

Merging props

By default, Inertia overwrites props with the same name when reloading a page. However, there are instances, - such as pagination, where that is not the desired behavior. In these cases, you can merge props - instead of overwriting them. + such as pagination, where that is not the desired behavior. In these cases, you can merge props instead of + overwriting them.

Prop merging only works during partial reloads. Full page visits will always @@ -28,141 +27,123 @@ export default function () {

Server side

- To specify that a prop should be merged, you can use the Inertia::merge() or Inertia::deepMerge() methods on - the prop value. -

-

- Use merge when you want to merge at the root level or specific properties, and{' '} - deepMerge when you want to recursively merge nested objects that contain arrays. -

- - input('page', 1); - $perPage = 5; - $offset = ($page - 1) * $perPage; - $tags = array_slice($allTags, $offset, $perPage); - - return Inertia::render('Tags/Index', [ - 'tags' => Inertia::merge($tags), - ]); - }); - `, - }, - { - name: 'Deep Merge', - language: 'php', - code: dedent` - Route::get('/users', function () { - $page = request()->input('page', 1); - $perPage = request()->input('per_page', 10); - - return Inertia::render('Users/Index', [ - 'results' => Inertia::deepMerge(User::paginate($perPage, page: $page)), - ]); - }); - `, - }, - ]} - /> - -

- During the merging process, if the value is an array, the incoming items will be{' '} - appended to the existing array by default, not merged by index. You can change this behavior - and gain more precise control using the methods described in the{' '} - fine-grained control section. You may also chain the{' '} - matchOn method to determine how existing items should be matched and updated. + To specify that a prop should be merged, you can use the Inertia::merge() method on the prop value.

Inertia::deepMerge($users)->matchOn('data.id'), - ]); + Route::get('/items', function () { + // Static array of tags + $allTags = [ + 'Laravel', 'React', 'Vue', 'Tailwind', 'Inertia', + 'PHP', 'JavaScript', 'TypeScript', 'Docker', 'Vite', + ]; + + // Get chunk of tags by page + $page = request()->input('page', 1); + $perPage = 5; + $offset = ($page - 1) * $perPage; + $tags = array_slice($allTags, $offset, $perPage); + + return Inertia::render('Tags/Index', [ + 'tags' => Inertia::merge($tags), + ]); + }); `} />

- In this example, Inertia will iterate over the users.data array and attempt to{' '} - match each item by its id field. If a match is found, the existing item will be replaced. - If no match is found, the new item will be appended. -

- - You may also pass an array of keys to matchOn to specify multiple keys for matching. - - -

Fine-grained control

-

- For more precise control over merging, you can use the append() and prepend() methods. - By default, Inertia::merge() appends at the root level. You can change this behavior or target - specific nested properties. + By default, Inertia::merge() appends new items to existing arrays at the root level. You can change + this to prepend items instead.

prepend(); - - // Target specific nested properties - Inertia::merge(User::paginate())->append('data'); + Inertia::merge($items)->prepend(); `} />

- You can also use prepend() to add items to the beginning of arrays, useful for chat messages - or activity feeds where newer items appear first. -

-

- Both methods can be chained together and support the matchOn parameter for item matching. + For more precise control, you can target specific nested properties while leaving the rest of the object + unchanged.

append('users', matchOn: 'username') - ->prepend('messages'); + // Only append to the 'data' array, replace everything else + Inertia::merge(User::paginate())->append('data'); + + // Prepend to the 'messages' array + Inertia::merge($chatData)->prepend('messages'); `} /> -

- You can pass arrays to target multiple properties at once. -

+

You can combine multiple operations and target several properties at once.

append('posts') + ->prepend('announcements'); + + // Target multiple properties Inertia::merge($dashboardData)->append(['notifications', 'activities']); `} />

- For advanced scenarios, pass a key-value array where the key is the property path and the value - is the matchOn field. + When merging arrays, you can use the matchOn parameter to determine how existing items should be + matched and updated instead of simply appending new ones.

append('data', matchOn: 'id'); + + // Multiple properties with different match fields Inertia::merge($complexData)->append([ 'users.data' => 'id', 'messages' => 'uuid', ]); `} /> +

+ In this example, Inertia will iterate over the arrays and attempt to match each item by the specified field. If + a match is found, the existing item will be replaced. If no match is found, the new item will be appended or + prepended as configured. +

+ + You may also pass an array of keys to matchOn to specify multiple keys for matching. + +

+ Instead of specifying which nested paths should be merged, you can use Inertia::deepMerge() + to recursively merge all nested objects that contain arrays. +

+ [ + ['id' => 4, 'text' => 'Hello there!', 'user' => 'Alice'], + ['id' => 5, 'text' => 'How are you?', 'user' => 'Bob'], + ], + 'online' => 12, + ]; + + return Inertia::render('Chat', [ + 'chat' => Inertia::deepMerge($chatData)->matchOn('messages.id'), + ]); + }); + `} + />

Client side

- On the client side, Inertia detects that this prop should be merged. If the prop returns an array, it will - append the response to the current prop value. If it's an object, it will merge the response with the current - prop value. If you have opted to deepMerge, Inertia ensures a deep merge of the entire structure. + On the client side, Inertia detects that this prop should be merged. If the prop returns an array, it will merge + the response with the current prop value according to your server-side configuration (append, prepend, or target + specific paths). If it's an object, it will merge the response with the current prop value. If you have opted to{' '} + deepMerge, Inertia ensures a deep merge of the entire structure.

Combining with deferred props

From 1dcc19d4f1a1e682c661d1cb8cd2b2be9520b211 Mon Sep 17 00:00:00 2001 From: Pascal Baljet Date: Thu, 25 Sep 2025 18:32:21 +0200 Subject: [PATCH 4/9] Update merging-props.jsx --- resources/js/Pages/merging-props.jsx | 44 ++++++++++++++-------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/resources/js/Pages/merging-props.jsx b/resources/js/Pages/merging-props.jsx index c5d47ab7..36583387 100644 --- a/resources/js/Pages/merging-props.jsx +++ b/resources/js/Pages/merging-props.jsx @@ -1,4 +1,4 @@ -import { A, Code, CodeBlock, H1, H2, Notice, P, TabbedCode } from '@/Components' +import { A, Code, CodeBlock, H1, H2, H3, P, TabbedCode } from '@/Components' import dedent from 'dedent-js' export const meta = { @@ -17,9 +17,9 @@ export default function () { <>

Merging props

- By default, Inertia overwrites props with the same name when reloading a page. However, there are instances, - such as pagination, where that is not the desired behavior. In these cases, you can merge props instead of - overwriting them. + Inertia overwrites props with the same name when reloading a page. However, you may need to merge new data with + existing data instead of replacing it entirely. For example, when implementing a "load more" button for + paginated results. In these cases, you can merge props instead of overwriting them.

Prop merging only works during partial reloads. Full page visits will always @@ -27,7 +27,8 @@ export default function () {

Server side

- To specify that a prop should be merged, you can use the Inertia::merge() method on the prop value. + To merge a prop instead of overwriting it, you may use the Inertia::merge() method when returning + your response.

- By default, Inertia::merge() appends new items to existing arrays at the root level. You can change - this to prepend items instead. + The Inertia::merge() method will append new items to existing arrays at the root level. You may + change this behavior to prepend items instead.

- For more precise control, you can target specific nested properties while leaving the rest of the object - unchanged. + For more precise control, you can target specific nested properties for merging while replacing the rest of the + object.

append(['notifications', 'activities']); `} /> +

Matching items

- When merging arrays, you can use the matchOn parameter to determine how existing items should be - matched and updated instead of simply appending new ones. + When merging arrays, you may use the matchOn parameter to match existing items by a specific field + and update them instead of simply appending new ones.

- In this example, Inertia will iterate over the arrays and attempt to match each item by the specified field. If - a match is found, the existing item will be replaced. If no match is found, the new item will be appended or - prepended as configured. + In the first example, Inertia will iterate over the data array and attempt to match each item by + its id field. If a match is found, the existing item will be replaced. If no match is found, the + new item will be appended as configured.

- - You may also pass an array of keys to matchOn to specify multiple keys for matching. - +

Deep merging

- Instead of specifying which nested paths should be merged, you can use Inertia::deepMerge() + Instead of specifying which nested paths should be merged, you may use Inertia::deepMerge() to recursively merge all nested objects that contain arrays.

Client side

- On the client side, Inertia detects that this prop should be merged. If the prop returns an array, it will merge - the response with the current prop value according to your server-side configuration (append, prepend, or target - specific paths). If it's an object, it will merge the response with the current prop value. If you have opted to{' '} - deepMerge, Inertia ensures a deep merge of the entire structure. + On the client side, Inertia will detect that the prop should be merged and handle the merging process + automatically. If the prop returns an array, it will merge the response with the current prop value according to + your server-side configuration (append, prepend, target specific paths, or deep merge). If you have used{' '} + deepMerge, Inertia will perform a deep merge of the entire structure.

Combining with deferred props

From 409fd9a6a30dbf18b0f840e0cdbba7ff32233c3e Mon Sep 17 00:00:00 2001 From: Pascal Baljet Date: Thu, 25 Sep 2025 22:39:14 +0200 Subject: [PATCH 5/9] Update merging-props.jsx --- resources/js/Pages/merging-props.jsx | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/resources/js/Pages/merging-props.jsx b/resources/js/Pages/merging-props.jsx index 36583387..cae42a33 100644 --- a/resources/js/Pages/merging-props.jsx +++ b/resources/js/Pages/merging-props.jsx @@ -1,4 +1,4 @@ -import { A, Code, CodeBlock, H1, H2, H3, P, TabbedCode } from '@/Components' +import { A, Code, CodeBlock, H1, H2, H3, Notice, P, TabbedCode } from '@/Components' import dedent from 'dedent-js' export const meta = { @@ -118,7 +118,7 @@ export default function () {

Deep merging

Instead of specifying which nested paths should be merged, you may use Inertia::deepMerge() - to recursively merge all nested objects that contain arrays. + to ensure a deep merge of the entire structure.

+ + Inertia::deepMerge() was introduced before Inertia::merge() had support for prepending + and targeting nested paths. In most cases, Inertia::merge() with its append and prepend methods + should be sufficient. +

Client side

On the client side, Inertia will detect that the prop should be merged and handle the merging process From fb23760c85b645dc17b58475ab886b981c46c4b5 Mon Sep 17 00:00:00 2001 From: Pascal Baljet Date: Thu, 25 Sep 2025 22:44:43 +0200 Subject: [PATCH 6/9] Update merging-props.jsx --- resources/js/Pages/merging-props.jsx | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/resources/js/Pages/merging-props.jsx b/resources/js/Pages/merging-props.jsx index cae42a33..f6f417f7 100644 --- a/resources/js/Pages/merging-props.jsx +++ b/resources/js/Pages/merging-props.jsx @@ -18,8 +18,7 @@ export default function () {

Merging props

Inertia overwrites props with the same name when reloading a page. However, you may need to merge new data with - existing data instead of replacing it entirely. For example, when implementing a "load more" button for - paginated results. In these cases, you can merge props instead of overwriting them. + existing data instead. For example, when implementing a "load more" button for paginated results.

Prop merging only works during partial reloads. Full page visits will always @@ -34,13 +33,13 @@ export default function () { language="php" children={dedent` Route::get('/items', function () { - // Static array of tags + // Static array of tags... $allTags = [ 'Laravel', 'React', 'Vue', 'Tailwind', 'Inertia', 'PHP', 'JavaScript', 'TypeScript', 'Docker', 'Vite', ]; - // Get chunk of tags by page + // Get chunk of tags by page... $page = request()->input('page', 1); $perPage = 5; $offset = ($page - 1) * $perPage; @@ -59,10 +58,10 @@ export default function () { prepend(); `} /> @@ -73,10 +72,10 @@ export default function () { append('data'); - // Prepend to the 'messages' array + // Prepend to the 'messages' array... Inertia::merge($chatData)->prepend('messages'); `} /> @@ -88,7 +87,7 @@ export default function () { ->append('posts') ->prepend('announcements'); - // Target multiple properties + // Target multiple properties... Inertia::merge($dashboardData)->append(['notifications', 'activities']); `} /> @@ -100,10 +99,10 @@ export default function () { append('data', matchOn: 'id'); - // Multiple properties with different match fields + // Multiple properties with different match fields... Inertia::merge($complexData)->append([ 'users.data' => 'id', 'messages' => 'uuid', From a8ceb2bcc53d5d426ee83dfcfb93940849c0721b Mon Sep 17 00:00:00 2001 From: Pascal Baljet Date: Fri, 26 Sep 2025 10:37:10 +0200 Subject: [PATCH 7/9] Update merging-props.jsx --- resources/js/Pages/merging-props.jsx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/resources/js/Pages/merging-props.jsx b/resources/js/Pages/merging-props.jsx index f6f417f7..22aec675 100644 --- a/resources/js/Pages/merging-props.jsx +++ b/resources/js/Pages/merging-props.jsx @@ -94,7 +94,7 @@ export default function () {

Matching items

When merging arrays, you may use the matchOn parameter to match existing items by a specific field - and update them instead of simply appending new ones. + and update them instead of appending new ones.

In the first example, Inertia will iterate over the data array and attempt to match each item by its id field. If a match is found, the existing item will be replaced. If no match is found, the - new item will be appended as configured. + new item will be appended.

Deep merging

From 4607f4491bda5fc2b55dd7f224323fab48be58e9 Mon Sep 17 00:00:00 2001 From: Pascal Baljet Date: Fri, 26 Sep 2025 13:00:16 +0200 Subject: [PATCH 8/9] Update merging-props.jsx --- resources/js/Pages/merging-props.jsx | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/resources/js/Pages/merging-props.jsx b/resources/js/Pages/merging-props.jsx index 22aec675..0deefbf8 100644 --- a/resources/js/Pages/merging-props.jsx +++ b/resources/js/Pages/merging-props.jsx @@ -1,12 +1,13 @@ -import { A, Code, CodeBlock, H1, H2, H3, Notice, P, TabbedCode } from '@/Components' +import { A, Code, CodeBlock, H1, H2, Notice, P, TabbedCode } from '@/Components' import dedent from 'dedent-js' export const meta = { title: 'Merging props', links: [ { url: '#top', name: 'Introduction' }, - { url: '#server-side', name: 'Server side' }, - { url: '#client-side', name: 'Client side' }, + { url: '#merge-methods', name: 'Merge methods' }, + { url: '#matching-items', name: 'Matching items' }, + { url: '#deep-merge', name: 'Deep merge' }, { url: '#combining-with-deferred-props', name: 'Deferred props' }, { url: '#resetting-props', name: 'Resetting props' }, ], @@ -24,7 +25,7 @@ export default function () { Prop merging only works during partial reloads. Full page visits will always replace props entirely, even if you've marked them for merging.

-

Server side

+

Merge methods

To merge a prop instead of overwriting it, you may use the Inertia::merge() method when returning your response. @@ -91,7 +92,10 @@ export default function () { Inertia::merge($dashboardData)->append(['notifications', 'activities']); `} /> -

Matching items

+

+ On the client side, Inertia handles all the merging automatically according to your server-side configuration. +

+

Matching items

When merging arrays, you may use the matchOn parameter to match existing items by a specific field and update them instead of appending new ones. @@ -114,7 +118,7 @@ export default function () { its id field. If a match is found, the existing item will be replaced. If no match is found, the new item will be appended.

-

Deep merging

+

Deep merge

Instead of specifying which nested paths should be merged, you may use Inertia::deepMerge() to ensure a deep merge of the entire structure. @@ -142,13 +146,6 @@ export default function () { and targeting nested paths. In most cases, Inertia::merge() with its append and prepend methods should be sufficient. -

Client side

-

- On the client side, Inertia will detect that the prop should be merged and handle the merging process - automatically. If the prop returns an array, it will merge the response with the current prop value according to - your server-side configuration (append, prepend, target specific paths, or deep merge). If you have used{' '} - deepMerge, Inertia will perform a deep merge of the entire structure. -

Combining with deferred props

You can also combine deferred props with mergeable props to defer the loading of From 020af23de883c6a8ff903412ff8cf250137df70a Mon Sep 17 00:00:00 2001 From: Pascal Baljet Date: Fri, 26 Sep 2025 17:22:23 +0200 Subject: [PATCH 9/9] Update merging-props.jsx --- resources/js/Pages/merging-props.jsx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/resources/js/Pages/merging-props.jsx b/resources/js/Pages/merging-props.jsx index 0deefbf8..1e5ac7d4 100644 --- a/resources/js/Pages/merging-props.jsx +++ b/resources/js/Pages/merging-props.jsx @@ -8,6 +8,7 @@ export const meta = { { url: '#merge-methods', name: 'Merge methods' }, { url: '#matching-items', name: 'Matching items' }, { url: '#deep-merge', name: 'Deep merge' }, + { url: '#client-side-visits', name: 'Client side visits' }, { url: '#combining-with-deferred-props', name: 'Deferred props' }, { url: '#resetting-props', name: 'Resetting props' }, ], @@ -146,6 +147,13 @@ export default function () { and targeting nested paths. In most cases, Inertia::merge() with its append and prepend methods should be sufficient. +

Client side visits

+

+ You can also merge props directly on the client side without making a server request using{' '} + client side visits. Inertia provides{' '} + prop helper methods that allow you to append, prepend, or replace prop + values. +

Combining with deferred props

You can also combine deferred props with mergeable props to defer the loading of