Merge pull request #14 from inertiajs/flash-data

Docs for `Inertia::flash()`

Author: pascalbaljet

docs.json

@@ -118,6 +118,7 @@
                         "group": "Data & Props",
                         "pages": [
                             "v2/data-props/shared-data",
+                            "v2/data-props/flash-data",
                             "v2/data-props/partial-reloads",
                             "v2/data-props/deferred-props",
                             "v2/data-props/merging-props",

v2/advanced/events.mdx

@@ -435,6 +435,48 @@ router.on('success', (event) => {
 
 The `success` event is not cancelable.
 
+## Flash
+
+<Badge>v2.3.3+</Badge>
+
+The `flash` event fires when [flash data](/v2/data-props/flash-data) is received from the server. This is useful for displaying toast notifications or handling temporary data in a central location.
+
+<CodeGroup>
+
+```js Vue icon="vuejs"
+import { router } from '@inertiajs/vue3'
+
+router.on('flash', (event) => {
+    if (event.detail.flash.toast) {
+        showToast(event.detail.flash.toast)
+    }
+})
+```
+
+```jsx React icon="react"
+import { router } from '@inertiajs/react'
+
+router.on('flash', (event) => {
+    if (event.detail.flash.toast) {
+        showToast(event.detail.flash.toast)
+    }
+})
+```
+
+```js Svelte icon="s"
+import { router } from '@inertiajs/svelte'
+
+router.on('flash', (event) => {
+    if (event.detail.flash.toast) {
+        showToast(event.detail.flash.toast)
+    }
+})
+```
+
+</CodeGroup>
+
+The `flash` event is not cancelable. [Partial reloads](/v2/data-props/partial-reloads) will only trigger the event if the flash data has changed.
+
 ## Error
 
 The `error` event fires when validation errors are present on "successful" page visits.

v2/data-props/flash-data.mdx

@@ -0,0 +1,274 @@
+---
+title: Flash Data
+---
+
+<Badge>v2.3.3+</Badge>
+
+Sometimes you may wish to send one-time data to your frontend that shouldn't reappear when users navigate through browser history. Unlike regular props, flash data isn't persisted in history state, making it ideal for success messages, newly created IDs, or other temporary values.
+
+## Flashing Data
+
+You may flash data using the `Inertia::flash()` method, passing a key and value or an array of key-value pairs.
+
+```php
+public function store(Request $request)
+{
+    $user = User::create($request->validated());
+
+    Inertia::flash('message', 'User created successfully!');
+
+    // Or flash multiple values at once...
+    Inertia::flash([
+        'message' => 'User created!',
+        'newUserId' => $user->id,
+    ]);
+
+    return back();
+}
+```
+
+Chaining with `back()` is also supported.
+
+```php
+return Inertia::flash('newUserId', $user->id)->back();
+```
+
+You may also chain `flash()` onto `render()`, or vice versa.
+
+```php
+return Inertia::render('Projects/Index', [
+    'projects' => $projects,
+])->flash('highlight', $project->id);
+
+// Or...
+
+return Inertia::flash('highlight', $project->id)
+    ->render('Projects/Index', ['projects' => $projects]);
+```
+
+Flash data is scoped to the current request. The middleware automatically persists it to the session when redirecting. After the flash data is sent to the client, it is cleared and will not appear in subsequent requests.
+
+## Accessing Flash Data
+
+Flash data is available on `page.flash`. You may also listen for the global `flash` event or use the `onFlash` callback.
+
+<CodeGroup>
+
+```vue Vue icon="vuejs"
+<script setup>
+import { usePage } from '@inertiajs/vue3'
+
+const page = usePage()
+</script>
+
+<template>
+    <div v-if="page.flash.toast" class="toast">
+        {{ page.flash.toast.message }}
+    </div>
+</template>
+```
+
+```jsx React icon="react"
+import { usePage } from '@inertiajs/react'
+
+export default function Layout({ children }) {
+    const { flash } = usePage()
+
+    return (
+        <>
+            {flash.toast && <div className="toast">{flash.toast.message}</div>}
+            {children}
+        </>
+    )
+}
+```
+
+```svelte Svelte icon="s"
+<script>
+    import { page } from '@inertiajs/svelte'
+</script>
+
+{#if $page.flash.toast}
+    <div class="toast">{$page.flash.toast.message}</div>
+{/if}
+```
+
+</CodeGroup>
+
+## The onFlash Callback
+
+You may use the `onFlash` callback to handle flash data when making requests.
+
+<CodeGroup>
+
+```js Vue icon="vuejs"
+import { router } from '@inertiajs/vue3'
+
+router.post('/users', data, {
+    onFlash: ({ newUserId }) => {
+        form.userId = newUserId
+    },
+})
+```
+
+```js React icon="react"
+import { router } from '@inertiajs/react'
+
+router.post('/users', data, {
+    onFlash: ({ newUserId }) => {
+        form.userId = newUserId
+    },
+})
+```
+
+```js Svelte icon="s"
+import { router } from '@inertiajs/svelte'
+
+router.post('/users', data, {
+    onFlash: ({ newUserId }) => {
+        form.userId = newUserId
+    },
+})
+```
+
+</CodeGroup>
+
+## Global Flash Event
+
+You may use the global `flash` event to handle flash data in a central location, such as a layout component. For more information on events, see the [events documentation](/v2/advanced/events).
+
+<CodeGroup>
+
+```js Vue icon="vuejs"
+import { router } from '@inertiajs/vue3'
+
+router.on('flash', (event) => {
+    if (event.detail.flash.toast) {
+        showToast(event.detail.flash.toast)
+    }
+})
+```
+
+```js React icon="react"
+import { router } from '@inertiajs/react'
+
+router.on('flash', (event) => {
+    if (event.detail.flash.toast) {
+        showToast(event.detail.flash.toast)
+    }
+})
+```
+
+```js Svelte icon="s"
+import { router } from '@inertiajs/svelte'
+
+router.on('flash', (event) => {
+    if (event.detail.flash.toast) {
+        showToast(event.detail.flash.toast)
+    }
+})
+```
+
+</CodeGroup>
+
+Native browser events are also supported.
+
+<CodeGroup>
+
+```js Vue icon="vuejs"
+document.addEventListener('inertia:flash', (event) => {
+    console.log(event.detail.flash)
+})
+```
+
+```js React icon="react"
+document.addEventListener('inertia:flash', (event) => {
+    console.log(event.detail.flash)
+})
+```
+
+```js Svelte icon="s"
+document.addEventListener('inertia:flash', (event) => {
+    console.log(event.detail.flash)
+})
+```
+
+</CodeGroup>
+
+The `flash` event is not cancelable. During [partial reloads](/v2/data-props/partial-reloads), it only fires if the flash data has changed.
+
+## Client-Side Flash
+
+You may set flash data on the client without a server request using the `router.flash()` method. Values are merged with existing flash data.
+
+<CodeGroup>
+
+```js Vue icon="vuejs"
+import { router } from '@inertiajs/vue3'
+
+router.flash('foo', 'bar')
+router.flash({ foo: 'bar' })
+```
+
+```js React icon="react"
+import { router } from '@inertiajs/react'
+
+router.flash('foo', 'bar')
+router.flash({ foo: 'bar' })
+```
+
+```js Svelte icon="s"
+import { router } from '@inertiajs/svelte'
+
+router.flash('foo', 'bar')
+router.flash({ foo: 'bar' })
+```
+
+</CodeGroup>
+
+A callback may also be passed to access the current flash data or replace it entirely.
+
+<CodeGroup>
+
+```js Vue icon="vuejs"
+import { router } from '@inertiajs/vue3'
+
+router.flash((current) => ({ ...current, bar: 'baz' }))
+router.flash(() => ({}))
+```
+
+```js React icon="react"
+import { router } from '@inertiajs/react'
+
+router.flash((current) => ({ ...current, bar: 'baz' }))
+router.flash(() => ({}))
+```
+
+```js Svelte icon="s"
+import { router } from '@inertiajs/svelte'
+
+router.flash((current) => ({ ...current, bar: 'baz' }))
+router.flash(() => ({}))
+```
+
+</CodeGroup>
+
+## TypeScript
+
+You may configure the flash data type globally using TypeScript's declaration merging.
+
+```ts
+// global.d.ts
+declare module '@inertiajs/core' {
+    export interface InertiaConfig {
+        flashDataType: {
+            toast?: {
+                type: 'success' | 'error'
+                message: string
+            }
+        }
+    }
+}
+```
+
+With this configuration, `page.flash.toast` will be properly typed as `{ type: "success" | "error"; message: string } | undefined`.