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.

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 merging simple arrays, and deepMerge when working with nested objects that contain arrays or complex structures, such as pagination objects.

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),
    ]);
});

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 matchOn method to determine how existing items should be matched and updated.

Inertia::render('Users/Index', [
    'users' => Inertia::deepMerge($users)->matchOn('data.id'),
]);

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.

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.

Combining with deferred props

You can also combine deferred props with mergeable props to defer the loading of the prop and ultimately mark it as mergeable once it's loaded.

Route::get('/users', function () {
    $page = request()->input('page', 1);
    $perPage = request()->input('per_page', 10);

    return Inertia::render('Users/Index', [
        'results' => Inertia::defer(fn() => User::paginate($perPage, page: $page))->deepMerge(),
    ]);
});

Resetting props

On the client side, you can indicate to the server that you would like to reset the prop. This is useful when you want to clear the prop value before merging new data, such as when the user enters a new search query on a paginated list.

The reset request option accepts an array of the props keys you would like to reset.

router.reload({
    reset: ['results'],
    // ...
})