Skip to content

Documentation for the matchOn method #418

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jun 26, 2025
Merged

Documentation for the matchOn method #418

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f754194
Documentation for the `matchOn` method
pascalbaljet Jun 26, 2025
e68971c
Bring back default behaviour notice
pascalbaljet Jun 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 26 additions & 5 deletions resources/js/Pages/merging-props.jsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
import { A, Code, H1, H2, P, Strong, 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: '#combining-with-deferred-props', name: 'Deferred props' },
{ url: '#resetting-props', name: 'Resetting props' },
],
}
Expand Down Expand Up @@ -71,15 +73,34 @@ export default function () {
]}
/>

<P>
During the merging process, if the value is an array, the incoming items will be{' '}
<em>appended</em> to the existing array, not merged by index. However, you may chain the{' '}
<Code>matchOn</Code> method to determine how existing items should be matched and updated.
</P>
<CodeBlock
language="php"
children={dedent`
Inertia::render('Users/Index', [
'users' => Inertia::deepMerge($users)->matchOn('data.id'),
]);
`}
/>
<P>
In this example, Inertia will iterate over the <Code>users.data</Code> array and attempt to{' '}
match each item by its <Code>id</Code> field. If a match is found, the existing item will be replaced.
If no match is found, the new item will be appended.
</P>
<Notice>
You may also pass an array of keys to <Code>matchOn</Code> to specify multiple keys for matching.
</Notice>
<H2>Client side</H2>
<P>
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 <Code>deepMerge</Code>, Inertia ensures a deep merge of the entire structure.
</P>
<P>
<Strong>Of note:</Strong> During the merging process, if the value is an array, the incoming items will be{' '}
<em>appended</em> to the existing array, not merged by index.
</P>
<H2>Combining with deferred props</H2>
<P>
You can also combine <A href="/deferred-props">deferred props</A> with mergeable props to defer the loading of
the prop and ultimately mark it as mergeable once it's loaded.
Expand Down