Docs for Inertia::flash()

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/data-props/flash-data.mdx

@@ -0,0 +1,272 @@
+---
+title: Flash Data
+---
+
+Flash data lets you send one-time data to the frontend. Unlike regular props, flash data isn't persisted in browser history state, so it won't reappear when navigating through history.
+
+## 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. When redirecting, the middleware automatically persists it to the session. 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 visits.
+
+<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.
+
+## 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" | "info";
+        message: string;
+      };
+    };
+  }
+}
+```
+
+With this configuration, `page.flash.toast` will be properly typed as `{ type: "success" | "error" | "info"; message: string } | undefined`.

v2/data-props/shared-data.mdx

@@ -147,81 +147,6 @@ export default function Layout({ children }) {
 
 </CodeGroup>
 
-## Flash Messages
+## Flash Data
 
-Another great use-case for shared data is flash messages. These are messages stored in the session only for the next request. For example, it's common to set a flash message after completing a task and before redirecting to a different page.
-
-Here's a simple way to implement flash messages in your Inertia applications. First, share the flash message on each request.
-
-```php
-class HandleInertiaRequests extends Middleware
-{
-    public function share(Request $request)
-    {
-        return array_merge(parent::share($request), [
-            'flash' => [
-                'message' => fn () => $request->session()->get('message')
-            ],
-        ]);
-    }
-}
-```
-
-Next, display the flash message in a frontend component, such as the site layout.
-
-<CodeGroup>
-
-```vue Vue icon="vuejs"
-<template>
-    <main>
-        <header></header>
-        <article>
-            <div v-if="$page.props.flash.message" class="alert">
-                {{ $page.props.flash.message }}
-            </div>
-            <slot />
-        </article>
-        <footer></footer>
-    </main>
-</template>
-```
-
-```jsx React icon="react"
-import { usePage } from '@inertiajs/react'
-
-export default function Layout({ children }) {
-    const { flash } = usePage().props
-
-    return (
-        <main>
-            <header></header>
-            <article>
-                {flash.message && (
-                    <div class="alert">{flash.message}</div>
-                )}
-                {children}
-            </article>
-            <footer></footer>
-        </main>
-    )
-}
-```
-
-```svelte Svelte icon="s"
-<script>
-    import { page } from '@inertiajs/svelte'
-</script>
-
-<main>
-    <header></header>
-    <article>
-        {#if $page.props.flash.message}
-            <div class="alert">{$page.props.flash.message}</div>
-        {/if}
-        <slot />
-    </article>
-    <footer></footer>
-</main>
-```
-
-</CodeGroup>
+For one-time notifications like toast messages or success alerts, you may use [flash data](/v2/data-props/flash-data). Unlike shared data, flash data is not persisted in the browser's history state, so it won't reappear when navigating through history.