react-router 7.15.1 → 7.17.0

package/docs/start/framework/navigating.md

@@ -0,0 +1,182 @@
+---
+title: Navigating
+order: 6
+---
+
+# Navigating
+
+[MODES: framework]
+
+## Introduction
+
+Users navigate your application with `<Link>`, `<NavLink>`, `<Form>`, `redirect`, and `useNavigate`.
+
+## NavLink
+
+This component is for navigation links that need to render active and pending states.
+
+```tsx
+import { NavLink } from "react-router";
+
+export function MyAppNav() {
+  return (
+    <nav>
+      <NavLink to="/" end>
+        Home
+      </NavLink>
+      <NavLink to="/trending" end>
+        Trending Concerts
+      </NavLink>
+      <NavLink to="/concerts">All Concerts</NavLink>
+      <NavLink to="/account">Account</NavLink>
+    </nav>
+  );
+}
+```
+
+`NavLink` renders default class names for different states for easy styling with CSS:
+
+```css
+a.active {
+  color: red;
+}
+
+a.pending {
+  animate: pulse 1s infinite;
+}
+
+a.transitioning {
+  /* css transition is running */
+}
+```
+
+It also has callback props on `className`, `style`, and `children` with the states for inline styling or conditional rendering:
+
+```tsx
+// className
+<NavLink
+  to="/messages"
+  className={({ isActive, isPending, isTransitioning }) =>
+    [
+      isPending ? "pending" : "",
+      isActive ? "active" : "",
+      isTransitioning ? "transitioning" : "",
+    ].join(" ")
+  }
+>
+  Messages
+</NavLink>
+```
+
+```tsx
+// style
+<NavLink
+  to="/messages"
+  style={({ isActive, isPending, isTransitioning }) => {
+    return {
+      fontWeight: isActive ? "bold" : "",
+      color: isPending ? "red" : "black",
+      viewTransitionName: isTransitioning ? "slide" : "",
+    };
+  }}
+>
+  Messages
+</NavLink>
+```
+
+```tsx
+// children
+<NavLink to="/tasks">
+  {({ isActive, isPending, isTransitioning }) => (
+    <span className={isActive ? "active" : ""}>Tasks</span>
+  )}
+</NavLink>
+```
+
+## Link
+
+Use `<Link>` when the link doesn't need active styling:
+
+```tsx
+import { Link } from "react-router";
+
+export function LoggedOutMessage() {
+  return (
+    <p>
+      You've been logged out.{" "}
+      <Link to="/login">Login again</Link>
+    </p>
+  );
+}
+```
+
+## Form
+
+The form component can be used to navigate with `URLSearchParams` provided by the user.
+
+```tsx
+<Form action="/search">
+  <input type="text" name="q" />
+</Form>
+```
+
+If the user enters "journey" into the input and submits it, they will navigate to:
+
+```
+/search?q=journey
+```
+
+Forms with `<Form method="post" />` will also navigate to the action prop but will submit the data as `FormData` instead of `URLSearchParams`. However, it is more common to `useFetcher()` to POST form data. See [Using Fetchers](../../how-to/fetchers).
+
+## redirect
+
+Inside of route loaders and actions, you can return a `redirect` to another URL.
+
+```tsx
+import { redirect } from "react-router";
+
+export async function loader({ request }) {
+  let user = await getUser(request);
+  if (!user) {
+    return redirect("/login");
+  }
+  return { userName: user.name };
+}
+```
+
+It is common to redirect to a new record after it has been created:
+
+```tsx
+import { redirect } from "react-router";
+
+export async function action({ request }) {
+  let formData = await request.formData();
+  let project = await createProject(formData);
+  return redirect(`/projects/${project.id}`);
+}
+```
+
+## useNavigate
+
+This hook allows the programmer to navigate the user to a new page without the user interacting. Usage of this hook should be uncommon. It's recommended to use the other APIs in this guide when possible.
+
+Reserve usage of `useNavigate` to situations where the user is _not_ interacting but you need to navigate, for example:
+
+- Logging them out after inactivity
+- Timed UIs like quizzes, etc.
+
+```tsx
+import { useNavigate } from "react-router";
+
+export function useLogoutAfterInactivity() {
+  let navigate = useNavigate();
+
+  useFakeInactivityHook(() => {
+    navigate("/logout");
+  });
+}
+```
+
+---
+
+Next: [Pending UI](./pending-ui)

package/docs/start/framework/pending-ui.md

@@ -0,0 +1,142 @@
+---
+title: Pending UI
+order: 7
+---
+
+# Pending UI
+
+[MODES: framework]
+
+## Introduction
+
+When the user navigates to a new route, or submits data to an action, the UI should immediately respond to the user's actions with a pending or optimistic state. Application code is responsible for this.
+
+## Global Pending Navigation
+
+When the user navigates to a new url, the loaders for the next page are awaited before the next page renders. You can get the pending state from `useNavigation`.
+
+```tsx
+import { useNavigation } from "react-router";
+
+export default function Root() {
+  const navigation = useNavigation();
+  const isNavigating = Boolean(navigation.location);
+
+  return (
+    <html>
+      <body>
+        {isNavigating && <GlobalSpinner />}
+        <Outlet />
+      </body>
+    </html>
+  );
+}
+```
+
+## Local Pending Navigation
+
+Pending indicators can also be localized to the link. NavLink's children, className, and style props can be functions that receive the pending state.
+
+```tsx
+import { NavLink } from "react-router";
+
+function Navbar() {
+  return (
+    <nav>
+      <NavLink to="/home">
+        {({ isPending }) => (
+          <span>Home {isPending && <Spinner />}</span>
+        )}
+      </NavLink>
+      <NavLink
+        to="/about"
+        style={({ isPending }) => ({
+          color: isPending ? "gray" : "black",
+        })}
+      >
+        About
+      </NavLink>
+    </nav>
+  );
+}
+```
+
+## Pending Form Submission
+
+When a form is submitted, the UI should immediately respond to the user's actions with a pending state. This is easiest to do with a [fetcher][use_fetcher] form because it has its own independent state (whereas normal forms cause a global navigation).
+
+```tsx filename=app/project.tsx lines=[10-12]
+import { useFetcher } from "react-router";
+
+function NewProjectForm() {
+  const fetcher = useFetcher();
+
+  return (
+    <fetcher.Form method="post">
+      <input type="text" name="title" />
+      <button type="submit">
+        {fetcher.state !== "idle"
+          ? "Submitting..."
+          : "Submit"}
+      </button>
+    </fetcher.Form>
+  );
+}
+```
+
+For non-fetcher form submissions, pending states are available on `useNavigation`.
+
+```tsx filename=app/projects/new.tsx
+import { useNavigation, Form } from "react-router";
+
+function NewProjectForm() {
+  const navigation = useNavigation();
+
+  return (
+    <Form method="post" action="/projects/new">
+      <input type="text" name="title" />
+      <button type="submit">
+        {navigation.formAction === "/projects/new"
+          ? "Submitting..."
+          : "Submit"}
+      </button>
+    </Form>
+  );
+}
+```
+
+## Optimistic UI
+
+When the future state of the UI is known by the form submission data, an optimistic UI can be implemented for instant UX.
+
+```tsx filename=app/project.tsx lines=[4-7]
+function Task({ task }) {
+  const fetcher = useFetcher();
+
+  let isComplete = task.status === "complete";
+  if (fetcher.formData) {
+    isComplete =
+      fetcher.formData.get("status") === "complete";
+  }
+
+  return (
+    <div>
+      <div>{task.title}</div>
+      <fetcher.Form method="post">
+        <button
+          name="status"
+          value={isComplete ? "incomplete" : "complete"}
+        >
+          {isComplete ? "Mark Incomplete" : "Mark Complete"}
+        </button>
+      </fetcher.Form>
+    </div>
+  );
+}
+```
+
+---
+
+Next: [Testing](./testing)
+
+[use_fetcher]: https://api.reactrouter.com/v7/functions/react-router.useFetcher.html

package/docs/start/framework/rendering.md

@@ -0,0 +1,59 @@
+---
+title: Rendering Strategies
+order: 4
+---
+
+# Rendering Strategies
+
+[MODES: framework]
+
+## Introduction
+
+There are three rendering strategies in React Router:
+
+- Client Side Rendering
+- Server Side Rendering
+- Static Pre-rendering
+
+## Client Side Rendering
+
+Routes are always client side rendered as the user navigates around the app. If you're looking to build a Single Page App, disable server rendering:
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  ssr: false,
+} satisfies Config;
+```
+
+## Server Side Rendering
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  ssr: true,
+} satisfies Config;
+```
+
+Server side rendering requires a deployment that supports it. Though it's a global setting, individual routes can still be statically pre-rendered. Routes can also use client data loading with `clientLoader` to avoid server rendering/fetching for their portion of the UI.
+
+## Static Pre-rendering
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  // return a list of URLs to prerender at build time
+  async prerender() {
+    return ["/", "/about", "/contact"];
+  },
+} satisfies Config;
+```
+
+Pre-rendering is a build-time operation that generates static HTML and client navigation data payloads for a list of URLs. This is useful for SEO and performance, especially for deployments without server rendering. When pre-rendering, route module loaders are used to fetch data at build time.
+
+---
+
+Next: [Data Loading](./data-loading)