react-router 7.15.1 → 8.3.0

package/docs/how-to/using-handle.md

@@ -0,0 +1,117 @@
+---
+title: Using handle
+---
+
+# Using `handle`
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+You can build dynamic UI elements like breadcrumbs based on your route hierarchy using the [`useMatches`][use-matches] hook and [`handle`][handle] route exports.
+
+## Understanding the Basics
+
+React Router provides access to all route matches and their data throughout your component tree. This allows routes to contribute metadata through the `handle` export that can be rendered by ancestor components.
+
+The `useMatches` hook combined with `handle` exports enables routes to contribute to rendering processes higher up the component tree than their actual render point. While we'll use breadcrumbs as an example, this pattern works for any scenario where you need routes to provide additional information to their ancestors.
+
+## Defining Route `handle`s
+
+We'll use a route structure like the following:
+
+```ts filename=app/routes.ts
+import { route } from "@react-router/dev/routes";
+
+export default [
+  route("parent", "./routes/parent.tsx", [
+    route("child", "./routes/child.tsx"),
+  ]),
+] satisfies RouteConfig;
+```
+
+Add a `breadcrumb` property to the "parent" route's `handle` export. You can name this property whatever makes sense for your use case.
+
+```tsx filename=app/routes/parent.tsx
+import { Link } from "react-router";
+
+export const handle = {
+  breadcrumb: () => <Link to="/parent">Some Route</Link>,
+};
+```
+
+You can define breadcrumbs for child routes as well:
+
+```tsx filename=app/routes/child.tsx
+import { Link } from "react-router";
+
+export const handle = {
+  breadcrumb: () => (
+    <Link to="/parent/child">Child Route</Link>
+  ),
+};
+```
+
+## Using Route `handle`s
+
+Use the `useMatches` hook in your root layout or any ancestor component to collect and render the components defined in the `handle` export(s):
+
+```tsx filename=app/root.tsx lines=[7,11,22-31]
+import {
+  Links,
+  Meta,
+  Outlet,
+  Scripts,
+  ScrollRestoration,
+  useMatches,
+} from "react-router";
+
+export function Layout({ children }) {
+  const matches = useMatches();
+
+  return (
+    <html lang="en">
+      <head>
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        <header>
+          <ol>
+            {matches
+              .filter(
+                (match) =>
+                  match.handle && match.handle.breadcrumb,
+              )
+              .map((match, index) => (
+                <li key={index}>
+                  {match.handle.breadcrumb(match)}
+                </li>
+              ))}
+          </ol>
+        </header>
+        {children}
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+
+export default function App() {
+  return <Outlet />;
+}
+```
+
+The `match` object is passed to each breadcrumb function, giving you access to `match.data` (from loaders) and other route information to create dynamic breadcrumbs based on your route's data.
+
+This pattern provides a clean way for routes to contribute metadata that can be consumed and rendered by ancestor components.
+
+## Additional Resources
+
+- [`useMatches`][use-matches]
+- [`handle`][handle]
+
+[use-matches]: ../api/hooks/useMatches
+[handle]: ../start/framework/route-module#handle

package/docs/how-to/view-transitions.md

@@ -0,0 +1,237 @@
+---
+title: View Transitions
+---
+
+# View Transitions
+
+[MODES: framework, data]
+
+<br/>
+<br/>
+
+Enable smooth animations between page transitions in your React Router applications using the [View Transitions API][view-transitions-api]. This feature allows you to create seamless visual transitions during client-side navigation.
+
+## Basic View Transition
+
+### 1. Enable view transitions on navigation
+
+The simplest way to enable view transitions is by adding the `viewTransition` prop to your `Link`, `NavLink`, or `Form` components. This automatically wraps the navigation update in `document.startViewTransition()`.
+
+```tsx
+<Link to="/about" viewTransition>
+  About
+</Link>
+```
+
+Without any additional CSS, this provides a basic cross-fade animation between pages.
+
+### 2. Enable view transitions with programmatic navigation
+
+When using programmatic navigation with the `useNavigate` hook, you can enable view transitions by passing the `viewTransition: true` option:
+
+```tsx
+import { useNavigate } from "react-router";
+
+function NavigationButton() {
+  const navigate = useNavigate();
+
+  return (
+    <button
+      onClick={() =>
+        navigate("/about", { viewTransition: true })
+      }
+    >
+      About
+    </button>
+  );
+}
+```
+
+This provides the same cross-fade animation as using the `viewTransition` prop on Link components.
+
+For more information on using the View Transitions API, please refer to the ["Smooth transitions with the View Transition API" guide][view-transitions-guide] from the Google Chrome team.
+
+## Image Gallery Example
+
+Let's build an image gallery that demonstrates how to trigger and use view transitions. We'll create a list of images that expand into a detail view with smooth animations.
+
+### 1. Create the image gallery route
+
+```tsx filename=routes/image-gallery.tsx
+import { NavLink } from "react-router";
+
+export const images = [
+  "https://remix.run/blog-images/headers/the-future-is-now.jpg",
+  "https://remix.run/blog-images/headers/waterfall.jpg",
+  "https://remix.run/blog-images/headers/webpack.png",
+  // ... more images ...
+];
+
+export default function ImageGalleryRoute() {
+  return (
+    <div className="image-list">
+      <h1>Image List</h1>
+      <div>
+        {images.map((src, idx) => (
+          <NavLink
+            key={src}
+            to={`/image/${idx}`}
+            viewTransition // Enable view transitions for this link
+          >
+            <p>Image Number {idx}</p>
+            <img
+              className="max-w-full contain-layout"
+              src={src}
+            />
+          </NavLink>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### 2. Add transition styles
+
+Define view transition names and animations for elements that should transition smoothly between routes.
+
+```css filename=app.css
+/* Layout styles for the image grid */
+.image-list > div {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  column-gap: 10px;
+}
+
+.image-list h1 {
+  font-size: 2rem;
+  font-weight: 600;
+}
+
+.image-list img {
+  max-width: 100%;
+  contain: layout;
+}
+
+.image-list p {
+  width: fit-content;
+}
+
+/* Assign transition names to elements during navigation */
+.image-list a.transitioning img {
+  view-transition-name: image-expand;
+}
+
+.image-list a.transitioning p {
+  view-transition-name: image-title;
+}
+```
+
+### 3. Create the image detail route
+
+The detail view needs to use the same view transition names to create a seamless animation.
+
+```tsx filename=routes/image-details.tsx
+import { Link } from "react-router";
+import { images } from "./home";
+import type { Route } from "./+types/image-details";
+
+export default function ImageDetailsRoute({
+  params,
+}: Route.ComponentProps) {
+  return (
+    <div className="image-detail">
+      <Link to="/" viewTransition>
+        Back
+      </Link>
+      <h1>Image Number {params.id}</h1>
+      <img src={images[Number(params.id)]} />
+    </div>
+  );
+}
+```
+
+### 4. Add matching transition styles for the detail view
+
+```css filename=app.css
+/* Match transition names from the list view */
+.image-detail h1 {
+  font-size: 2rem;
+  font-weight: 600;
+  width: fit-content;
+  view-transition-name: image-title;
+}
+
+.image-detail img {
+  max-width: 100%;
+  contain: layout;
+  view-transition-name: image-expand;
+}
+```
+
+## Advanced Usage
+
+You can control view transitions more precisely using either render props or the `useViewTransitionState` hook.
+
+### 1. Using render props
+
+```tsx filename=routes/image-gallery.tsx
+<NavLink to={`/image/${idx}`} viewTransition>
+  {({ isTransitioning }) => (
+    <>
+      <p
+        style={{
+          viewTransitionName: isTransitioning
+            ? "image-title"
+            : "none",
+        }}
+      >
+        Image Number {idx}
+      </p>
+      <img
+        src={src}
+        style={{
+          viewTransitionName: isTransitioning
+            ? "image-expand"
+            : "none",
+        }}
+      />
+    </>
+  )}
+</NavLink>
+```
+
+### 2. Using the `useViewTransitionState` hook
+
+```tsx filename=routes/image-gallery.tsx
+function NavImage(props: { src: string; idx: number }) {
+  const href = `/image/${props.idx}`;
+  // Hook provides transition state for specific route
+  const isTransitioning = useViewTransitionState(href);
+
+  return (
+    <Link to={href} viewTransition>
+      <p
+        style={{
+          viewTransitionName: isTransitioning
+            ? "image-title"
+            : "none",
+        }}
+      >
+        Image Number {props.idx}
+      </p>
+      <img
+        src={props.src}
+        style={{
+          viewTransitionName: isTransitioning
+            ? "image-expand"
+            : "none",
+        }}
+      />
+    </Link>
+  );
+}
+```
+
+[view-transitions-api]: https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition
+[view-transitions-guide]: https://developer.chrome.com/docs/web-platform/view-transitions

package/docs/how-to/webhook.md

@@ -0,0 +1,50 @@
+---
+title: Webhooks
+# can make a quick how-to on creating a webhook, this was copy/pasted from another doc, needs to be reviewed first
+hidden: true
+---
+
+# Webhooks
+
+Resource routes can be used to handle webhooks. For example, you can create a webhook that receives notifications from GitHub when a new commit is pushed to a repository:
+
+```tsx
+import type { Route } from "./+types/github";
+
+import crypto from "node:crypto";
+
+export const action = async ({
+  request,
+}: Route.ActionArgs) => {
+  if (request.method !== "POST") {
+    return Response.json(
+      { message: "Method not allowed" },
+      {
+        status: 405,
+      },
+    );
+  }
+  const payload = await request.json();
+
+  /* Validate the webhook */
+  const signature = request.headers.get(
+    "X-Hub-Signature-256",
+  );
+  const generatedSignature = `sha256=${crypto
+    .createHmac("sha256", process.env.GITHUB_WEBHOOK_SECRET)
+    .update(JSON.stringify(payload))
+    .digest("hex")}`;
+  if (signature !== generatedSignature) {
+    return Response.json(
+      { message: "Signature mismatch" },
+      {
+        status: 401,
+      },
+    );
+  }
+
+  /* process the webhook (e.g. enqueue a background job) */
+
+  return Response.json({ success: true });
+};
+```

package/docs/index.md

@@ -0,0 +1,36 @@
+---
+title: React Router Home
+order: 1
+---
+
+# React Router Home
+
+React Router is a multi-strategy router for React. You can use it maximally as a React framework or as minimally as you want.
+
+## Getting Started
+
+There are three primary ways, or "modes", to use it in your app, so there are three guides to get you started.
+
+- [Declarative](./start/declarative/installation)
+- [Data](./start/data/installation)
+- [Framework](./start/framework/installation)
+
+Learn which mode is right for you in [Picking a Mode](./start/modes).
+
+## Using These Guides
+
+Across the docs you'll see the following icons:
+
+[MODES: framework, data, declarative]
+
+<p></p>
+
+These icons indicate which mode the content is relevant to.
+
+Additional auto-generated reference documentation is available:
+
+[Autogenerated Reference Docs ↗](https://api.reactrouter.com/v8/)
+
+## Upgrading
+
+If you are caught up on future flags, [upgrading from React Router v7](./upgrading/v7) is generally non-breaking.

package/docs/start/data/actions.md

@@ -0,0 +1,138 @@
+---
+title: Actions
+order: 5
+---
+
+# Actions
+
+[MODES: data]
+
+## Defining Actions
+
+Data mutations are done through Route actions defined on the `action` property of a route object. When the action completes, all loader data on the page is revalidated to keep your UI in sync with the data without writing any code to do it.
+
+```tsx
+import { createBrowserRouter } from "react-router";
+import { someApi } from "./api";
+
+let router = createBrowserRouter([
+  {
+    path: "/projects/:projectId",
+    Component: Project,
+    action: async ({ request }) => {
+      let formData = await request.formData();
+      let title = formData.get("title");
+      let project = await someApi.updateProject({ title });
+      return project;
+    },
+  },
+]);
+```
+
+## Calling Actions
+
+Actions are called declaratively through `<Form>` and imperatively through `useSubmit` (or `<fetcher.Form>` and `fetcher.submit`) by referencing the route's path and a "post" method.
+
+### Calling actions with a Form
+
+```tsx
+import { Form } from "react-router";
+
+function SomeComponent() {
+  return (
+    <Form action="/projects/123" method="post">
+      <input type="text" name="title" />
+      <button type="submit">Submit</button>
+    </Form>
+  );
+}
+```
+
+This will cause a navigation and a new entry will be added to the browser history.
+
+### Calling actions with useSubmit
+
+You can submit form data to an action imperatively with `useSubmit`.
+
+```tsx
+import { useCallback } from "react";
+import { useSubmit } from "react-router";
+import { useFakeTimer } from "fake-lib";
+
+function useQuizTimer() {
+  let submit = useSubmit();
+
+  let cb = useCallback(() => {
+    submit(
+      { quizTimedOut: true },
+      { action: "/end-quiz", method: "post" },
+    );
+  }, []);
+
+  let tenMinutes = 10 * 60 * 1000;
+  useFakeTimer(tenMinutes, cb);
+}
+```
+
+This will cause a navigation and a new entry will be added to the browser history.
+
+### Calling actions with a fetcher
+
+Fetchers allow you to submit data to actions (and loaders) without causing a navigation (no new entries in the browser history).
+
+```tsx
+import { useFetcher } from "react-router";
+
+function Task() {
+  let fetcher = useFetcher();
+  let busy = fetcher.state !== "idle";
+
+  return (
+    <fetcher.Form method="post" action="/update-task/123">
+      <input type="text" name="title" />
+      <button type="submit">
+        {busy ? "Saving..." : "Save"}
+      </button>
+    </fetcher.Form>
+  );
+}
+```
+
+They also have the imperative `submit` method.
+
+```tsx
+fetcher.submit(
+  { title: "New Title" },
+  { action: "/update-task/123", method: "post" },
+);
+```
+
+See the [Using Fetchers][fetchers] guide for more information.
+
+## Accessing Action Data
+
+Actions can return data available through `useActionData` in the route component or `fetcher.data` when using a fetcher.
+
+```tsx
+function Project() {
+  let actionData = useActionData();
+  return (
+    <div>
+      <h1>Project</h1>
+      <Form method="post">
+        <input type="text" name="title" />
+        <button type="submit">Submit</button>
+      </Form>
+      {actionData ? (
+        <p>{actionData.title} updated</p>
+      ) : null}
+    </div>
+  );
+}
+```
+
+---
+
+Next: [Navigating](./navigating)
+
+[fetchers]: ../../how-to/fetchers