Skip to content

Commit d892f9d

Browse files
joetannenbaumjoetannenbaum
authored
Merge pull request #442 from inertiajs/props-docs
Add documentation for props and the new `ProvidesInertiaProperty` and `ProvidesInertiaProperties` interfaces
2 parents 51a7156 + a520ad4 commit d892f9d

File tree

1 file changed

+227
-3
lines changed

1 file changed

+227
-3
lines changed

‎resources/js/Pages/responses.jsx

Lines changed: 227 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,9 @@ export const meta = {
55
title: 'Responses',
66
links: [
77
{ url: '#creating-responses', name: 'Creating responses' },
8+
{ url: '#properties', name: 'Properties' },
9+
{ url: '#provides-inertia-property', name: 'ProvidesInertiaProperty interface' },
10+
{ url: '#provides-inertia-properties', name: 'ProvidesInertiaProperties interface' },
811
{ url: '#root-template-data', name: 'Root template data' },
912
{ url: '#maximum-response-size', name: 'Maximum response size' },
1013
],
@@ -18,10 +21,10 @@ export default function () {
1821
<P>
1922
Creating an Inertia response is simple. To get started, invoke the <Code>Inertia::render()</Code> method within
2023
your controller or route, providing both the name of the <A href="/pages">JavaScript page component</A> that you
21-
wish to render, as well as any props (data) for the page.
24+
wish to render, as well as any properties (data) for the page.
2225
</P>
2326
<P>
24-
In the example below, we will pass a single prop (<Code>event</Code>) which contains four attributes (
27+
In the example below, we will pass a single property (<Code>event</Code>) which contains four attributes (
2528
<Code>id</Code>, <Code>title</Code>, <Code>start_date</Code> and <Code>description</Code>) to the{' '}
2629
<Code>Event/Show</Code> page component.
2730
</P>
@@ -66,6 +69,227 @@ export default function () {
6669
To ensure that pages load quickly, only return the minimum data required for the page. Also, be aware that all
6770
data returned from the controllers will be visible client-side, so be sure to omit sensitive information.
6871
</Notice>
72+
<H2>Properties</H2>
73+
<P>
74+
To pass data from the server to your page components, you can use properties. You can pass various types of values as
75+
props, including primitive types, arrays, objects, and several Laravel-specific types that are automatically resolved:
76+
</P>
77+
<TabbedCode
78+
examples={[
79+
{
80+
name: 'Laravel',
81+
language: 'php',
82+
code: dedent`
83+
use App\\Models\\User;
84+
use Illuminate\\Http\\Resources\\Json\\JsonResource;
85+
86+
Inertia::render('Dashboard', [
87+
// Primitive values
88+
'title' => 'Dashboard',
89+
'count' => 42,
90+
'active' => true,
91+
92+
// Arrays and objects
93+
'settings' => ['theme' => 'dark', 'notifications' => true],
94+
95+
// Arrayable objects (Collections, Models, etc.)
96+
'user' => auth()->user(), // Eloquent model
97+
'users' => User::all(), // Eloquent collection
98+
99+
// API Resources
100+
'profile' => new UserResource(auth()->user()),
101+
102+
// Responsable objects
103+
'data' => new JsonResponse(['key' => 'value']),
104+
105+
// Closures
106+
'timestamp' => fn() => now()->timestamp,
107+
]);
108+
`,
109+
},
110+
]}
111+
/>
112+
<P>
113+
Arrayable objects like Eloquent models and collections are automatically converted using their <Code>toArray()</Code> method.
114+
Responsable objects like API resources and JSON responses are resolved through their <Code>toResponse()</Code> method.
115+
</P>
116+
<H2>ProvidesInertiaProperty interface</H2>
117+
<P>
118+
When passing props to your components, you may want to create custom classes that can transform themselves into the
119+
appropriate data format. While Laravel's <Code>Arrayable</Code> interface simply converts objects to arrays, Inertia
120+
offers the more powerful <Code>ProvidesInertiaProperty</Code> interface for context-aware transformations.
121+
</P>
122+
<P>
123+
This interface requires a <Code>toInertiaProperty</Code> method that receives a <Code>PropertyContext</Code> object
124+
containing the property key (<Code>$context->key</Code>), all props for the page (<Code>$context->props</Code>), and the
125+
request instance (<Code>$context->request</Code>).
126+
</P>
127+
<TabbedCode
128+
examples={[
129+
{
130+
name: 'Laravel',
131+
language: 'php',
132+
code: dedent`
133+
use Inertia\\PropertyContext;
134+
use Inertia\\ProvidesInertiaProperty;
135+
136+
class UserAvatar implements ProvidesInertiaProperty
137+
{
138+
public function __construct(protected User $user, protected int $size = 64) {}
139+
140+
public function toInertiaProperty(PropertyContext $context): mixed
141+
{
142+
return $this->user->avatar
143+
? Storage::url($this->user->avatar)
144+
: "https://ui-avatars.com/api/?name={$this->user->name}&size={$this->size}";
145+
}
146+
}
147+
`,
148+
},
149+
]}
150+
/>
151+
<P>
152+
You can use this class directly as a prop value:
153+
</P>
154+
<TabbedCode
155+
examples={[
156+
{
157+
name: 'Laravel',
158+
language: 'php',
159+
code: dedent`
160+
Inertia::render('Profile', [
161+
'user' => $user,
162+
'avatar' => new UserAvatar($user, 128),
163+
]);
164+
`,
165+
},
166+
]}
167+
/>
168+
<P>
169+
The <Code>PropertyContext</Code> gives you access to the property key, which enables powerful patterns like merging
170+
with shared data:
171+
</P>
172+
<TabbedCode
173+
examples={[
174+
{
175+
name: 'Laravel',
176+
language: 'php',
177+
code: dedent`
178+
use Inertia\\Inertia;
179+
use Inertia\\PropertyContext;
180+
use Inertia\\ProvidesInertiaProperty;
181+
182+
class MergeWithShared implements ProvidesInertiaProperty
183+
{
184+
public function __construct(protected array $items = []) {}
185+
186+
public function toInertiaProperty(PropertyContext $context): mixed
187+
{
188+
// Access the property key to get shared data
189+
$shared = Inertia::getShared($context->key, []);
190+
191+
// Merge with the new items
192+
return array_merge($shared, $this->items);
193+
}
194+
}
195+
196+
// Usage
197+
Inertia::share('notifications', ['Welcome back!']);
198+
199+
return Inertia::render('Dashboard', [
200+
'notifications' => new MergeWithShared(['New message received']),
201+
// Result: ['Welcome back!', 'New message received']
202+
]);
203+
`,
204+
},
205+
]}
206+
/>
207+
<H2>ProvidesInertiaProperties interface</H2>
208+
<P>
209+
In some situations you may want to group related props together for reusability across different pages. You can
210+
accomplish this by implementing the <Code>ProvidesInertiaProperties</Code> interface.
211+
</P>
212+
<P>
213+
This interface requires a <Code>toInertiaProperties</Code> method that returns an array of key-value pairs. The
214+
method receives a <Code>RenderContext</Code> object containing the component name (<Code>$context->component</Code>)
215+
and request instance (<Code>$context->request</Code>).
216+
</P>
217+
<TabbedCode
218+
examples={[
219+
{
220+
name: 'Laravel',
221+
language: 'php',
222+
code: dedent`
223+
use App\\Models\\User;
224+
use Illuminate\\Container\\Attributes\\CurrentUser;
225+
use Inertia\\RenderContext;
226+
use Inertia\\ProvidesInertiaProperties;
227+
228+
class UserPermissions implements ProvidesInertiaProperties
229+
{
230+
public function __construct(#[CurrentUser] protected User $user) {}
231+
232+
public function toInertiaProperties(RenderContext $context): array
233+
{
234+
return [
235+
'canEdit' => $this->user->can('edit'),
236+
'canDelete' => $this->user->can('delete'),
237+
'canPublish' => $this->user->can('publish'),
238+
'isAdmin' => $this->user->hasRole('admin'),
239+
];
240+
}
241+
}
242+
`,
243+
},
244+
]}
245+
/>
246+
<P>
247+
You can use these prop classes directly in the <Code>render()</Code> and <Code>with()</Code> methods:
248+
</P>
249+
<TabbedCode
250+
examples={[
251+
{
252+
name: 'Laravel',
253+
language: 'php',
254+
code: dedent`
255+
public function index(UserPermissions $permissions)
256+
{
257+
return Inertia::render('UserProfile', $permissions);
258+
259+
// or...
260+
261+
return Inertia::render('UserProfile')->with($permissions);
262+
}
263+
`,
264+
},
265+
]}
266+
/>
267+
<P>
268+
You can also combine multiple prop classes with other props in an array:
269+
</P>
270+
<TabbedCode
271+
examples={[
272+
{
273+
name: 'Laravel',
274+
language: 'php',
275+
code: dedent`
276+
public function index(UserPermissions $permissions)
277+
{
278+
return Inertia::render('UserProfile', [
279+
'user' => auth()->user(),
280+
$permissions,
281+
]);
282+
283+
// or using method chaining...
284+
285+
return Inertia::render('UserProfile')
286+
->with('user', auth()->user())
287+
->with($permissions);
288+
}
289+
`,
290+
},
291+
]}
292+
/>
69293
<H2>Root template data</H2>
70294
<P>
71295
There are situations where you may want to access your prop data in your application's root Blade template. For
@@ -84,7 +308,7 @@ export default function () {
84308
]}
85309
/>
86310
<P>
87-
Sometimes you may even want to provide data to the root template that will not be sent to your JavaScript page /
311+
Sometimes you may even want to provide data to the root template that will not be sent to your JavaScript page
88312
component. This can be accomplished by invoking the <Code>withViewData</Code> method.
89313
</P>
90314
<TabbedCode

0 commit comments

Comments
 (0)