react-router 7.16.0 → 8.0.0-pre.0

package/docs/start/data/routing.md

@@ -0,0 +1,281 @@
+---
+title: Routing
+order: 2
+---
+
+# Routing
+
+[MODES: data]
+
+## Configuring Routes
+
+Routes are configured as the first argument to `createBrowserRouter`. At a minimum, you need a path and component:
+
+```tsx
+import { createBrowserRouter } from "react-router";
+
+function Root() {
+  return <h1>Hello world</h1>;
+}
+
+const router = createBrowserRouter([
+  { path: "/", Component: Root },
+]);
+```
+
+Here is a larger sample route config:
+
+```ts filename=app/routes.ts
+createBrowserRouter([
+  {
+    path: "/",
+    Component: Root,
+    children: [
+      { index: true, Component: Home },
+      { path: "about", Component: About },
+      {
+        path: "auth",
+        Component: AuthLayout,
+        children: [
+          { path: "login", Component: Login },
+          { path: "register", Component: Register },
+        ],
+      },
+      {
+        path: "concerts",
+        children: [
+          { index: true, Component: ConcertsHome },
+          { path: ":city", Component: ConcertsCity },
+          { path: "trending", Component: ConcertsTrending },
+        ],
+      },
+    ],
+  },
+]);
+```
+
+## Route Objects
+
+Route objects define the behavior of a route beyond just the path and component, like data loading and actions. We'll go into more detail in the [Route Object guide](./route-object), but here's a quick example of a loader.
+
+```tsx filename=app/team.tsx
+import {
+  createBrowserRouter,
+  useLoaderData,
+} from "react-router";
+
+createBrowserRouter([
+  {
+    path: "/teams/:teamId",
+    loader: async ({ params }) => {
+      let team = await fetchTeam(params.teamId);
+      return { name: team.name };
+    },
+    Component: Team,
+  },
+]);
+
+function Team() {
+  let data = useLoaderData();
+  return <h1>{data.name}</h1>;
+}
+```
+
+## Nested Routes
+
+Routes can be nested inside parent routes through `children`.
+
+```ts filename=app/routes.ts
+createBrowserRouter([
+  {
+    path: "/dashboard",
+    Component: Dashboard,
+    children: [
+      { index: true, Component: Home },
+      { path: "settings", Component: Settings },
+    ],
+  },
+]);
+```
+
+The path of the parent is automatically included in the child, so this config creates both `"/dashboard"` and `"/dashboard/settings"` URLs.
+
+Child routes are rendered through the `<Outlet/>` in the parent route.
+
+```tsx filename=app/dashboard.tsx
+import { Outlet } from "react-router";
+
+export default function Dashboard() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      {/* will either be <Home> or <Settings> */}
+      <Outlet />
+    </div>
+  );
+}
+```
+
+## Layout Routes
+
+Omitting the `path` in a route creates new [Nested Routes](#nested-routes) for its children without adding any segments to the URL.
+
+```tsx lines=[3,16]
+createBrowserRouter([
+  {
+    // no path on this parent route, just the component
+    Component: MarketingLayout,
+    children: [
+      { index: true, Component: Home },
+      { path: "contact", Component: Contact },
+    ],
+  },
+
+  {
+    path: "projects",
+    children: [
+      { index: true, Component: ProjectsHome },
+      {
+        // again, no path, just a component for the layout
+        Component: ProjectLayout,
+        children: [
+          { path: ":pid", Component: Project },
+          { path: ":pid/edit", Component: EditProject },
+        ],
+      },
+    ],
+  },
+]);
+```
+
+Note that:
+
+- `Home` and `Contact` will be rendered into the `MarketingLayout` outlet
+- `Project` and `EditProject` will be rendered into the `ProjectLayout` outlet while `ProjectsHome` will not.
+
+## Index Routes
+
+Index routes are defined by setting `index: true` on a route object without a path.
+
+```ts
+{ index: true, Component: Home }
+```
+
+Index routes render into their parent's [Outlet][outlet] at their parent's URL (like a default child route).
+
+```ts lines=[4,5,10,11]
+import { createBrowserRouter } from "react-router";
+
+createBrowserRouter([
+  // renders at "/"
+  { index: true, Component: Home },
+  {
+    Component: Dashboard,
+    path: "/dashboard",
+    children: [
+      // renders at "/dashboard"
+      { index: true, Component: DashboardHome },
+      { path: "settings", Component: DashboardSettings },
+    ],
+  },
+]);
+```
+
+Note that index routes can't have children.
+
+## Prefix Route
+
+A route with just a path and no component creates a group of routes with a path prefix.
+
+```tsx lines=[3]
+createBrowserRouter([
+  {
+    // no component, just a path
+    path: "/projects",
+    children: [
+      { index: true, Component: ProjectsHome },
+      { path: ":pid", Component: Project },
+      { path: ":pid/edit", Component: EditProject },
+    ],
+  },
+]);
+```
+
+This creates the routes `/projects`, `/projects/:pid`, and `/projects/:pid/edit` without introducing a layout component.
+
+## Dynamic Segments
+
+If a path segment starts with `:` then it becomes a "dynamic segment". When the route matches the URL, the dynamic segment will be parsed from the URL and provided as `params` to other router APIs.
+
+```ts lines=[2]
+{
+  path: "teams/:teamId",
+  loader: async ({ params }) => {
+    // params are available in loaders/actions
+    let team = await fetchTeam(params.teamId);
+    return { name: team.name };
+  },
+  Component: Team,
+}
+```
+
+```tsx
+import { useParams } from "react-router";
+
+function Team() {
+  // params are available in components through useParams
+  let params = useParams();
+  // ...
+}
+```
+
+You can have multiple dynamic segments in one route path:
+
+```ts
+{
+  path: "c/:categoryId/p/:productId";
+}
+```
+
+## Optional Segments
+
+You can make a route segment optional by adding a `?` to the end of the segment.
+
+```ts
+{
+  path: ":lang?/categories";
+}
+```
+
+You can have optional static segments, too:
+
+```ts
+{
+  path: "users/:userId/edit?";
+}
+```
+
+## Splats
+
+Also known as "catchall" and "star" segments. If a route path pattern ends with `/*` then it will match any characters following the `/`, including other `/` characters.
+
+```ts
+{
+  path: "files/*";
+  loader: async ({ params }) => {
+    params["*"]; // will contain the remaining URL after files/
+  };
+}
+```
+
+You can destructure the `*`, you just have to assign it a new name. A common name is `splat`:
+
+```tsx
+const { "*": splat } = params;
+```
+
+---
+
+Next: [Route Object](./route-object)
+
+[outlet]: https://api.reactrouter.com/v7/functions/react-router.Outlet.html

package/docs/start/data/testing.md

@@ -0,0 +1,8 @@
+---
+title: Testing
+order: 9
+---
+
+# Testing
+
+You can use `createRoutesStub` in data and framework modes. Please refer to the [Testing Guide](../framework/testing).

package/docs/start/declarative/index.md

@@ -0,0 +1,4 @@
+---
+title: Declarative Mode
+order: 4
+---

package/docs/start/declarative/installation.md

@@ -0,0 +1,43 @@
+---
+title: Installation
+order: 1
+---
+
+# Installation
+
+[MODES: declarative]
+
+## Introduction
+
+You can start with a React template from Vite and choose "React", otherwise bootstrap your application however you prefer.
+
+```shellscript nonumber
+npx create-vite@latest
+```
+
+Next install React Router from npm:
+
+```shellscript nonumber
+npm i react-router
+```
+
+Finally, render a `<BrowserRouter>` around your application:
+
+```tsx lines=[3,9-11]
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { BrowserRouter } from "react-router";
+import App from "./app";
+
+const root = document.getElementById("root");
+
+ReactDOM.createRoot(root).render(
+  <BrowserRouter>
+    <App />
+  </BrowserRouter>,
+);
+```
+
+---
+
+Next: [Routing](./routing)

package/docs/start/declarative/navigating.md

@@ -0,0 +1,133 @@
+---
+title: Navigating
+order: 3
+---
+
+# Navigating
+
+[MODES: declarative]
+
+## Introduction
+
+Users navigate your application with `<Link>`, `<NavLink>`, and `useNavigate`.
+
+## NavLink
+
+This component is for navigation links that need to render an active state.
+
+```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>
+  );
+}
+```
+
+Whenever a `NavLink` is active, it will automatically have an `.active` class name for easy styling with CSS:
+
+```css
+a.active {
+  color: red;
+}
+```
+
+It also has callback props on `className`, `style`, and `children` with the active state for inline styling or conditional rendering:
+
+```tsx
+// className
+<NavLink
+  to="/messages"
+  className={({ isActive }) =>
+    isActive ? "text-red-500" : "text-black"
+  }
+>
+  Messages
+</NavLink>
+```
+
+```tsx
+// style
+<NavLink
+  to="/messages"
+  style={({ isActive }) => ({
+    color: isActive ? "red" : "black",
+  })}
+>
+  Messages
+</NavLink>
+```
+
+```tsx
+// children
+<NavLink to="/message">
+  {({ isActive }) => (
+    <span className={isActive ? "active" : ""}>
+      {isActive ? "👉" : ""} 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>
+  );
+}
+```
+
+## useNavigate
+
+This hook allows the programmer to navigate the user to a new page without the user interacting.
+
+For normal navigation, it's best to use `Link` or `NavLink`. They provide a better default user experience like keyboard events, accessibility labeling, "open in new window", right click context menus, etc.
+
+Reserve usage of `useNavigate` to situations where the user is _not_ interacting but you need to navigate, for example:
+
+- After a form submission completes
+- Logging them out after inactivity
+- Timed UIs like quizzes, etc.
+
+```tsx
+import { useNavigate } from "react-router";
+
+export function LoginPage() {
+  let navigate = useNavigate();
+
+  return (
+    <>
+      <MyHeader />
+      <MyLoginForm
+        onSuccess={() => {
+          navigate("/dashboard");
+        }}
+      />
+      <MyFooter />
+    </>
+  );
+}
+```
+
+---
+
+Next: [Url values](./url-values)

package/docs/start/declarative/routing.md

@@ -0,0 +1,237 @@
+---
+title: Routing
+order: 2
+---
+
+# Routing
+
+[MODES: declarative]
+
+## Configuring Routes
+
+Routes are configured by rendering `<Routes>` and `<Route>` that couple URL segments to UI elements.
+
+```tsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { BrowserRouter, Routes, Route } from "react-router";
+import App from "./app";
+
+const root = document.getElementById("root");
+
+ReactDOM.createRoot(root).render(
+  <BrowserRouter>
+    <Routes>
+      <Route path="/" element={<App />} />
+    </Routes>
+  </BrowserRouter>,
+);
+```
+
+Here's a larger sample config:
+
+```tsx
+<Routes>
+  <Route index element={<Home />} />
+  <Route path="about" element={<About />} />
+
+  <Route element={<AuthLayout />}>
+    <Route path="login" element={<Login />} />
+    <Route path="register" element={<Register />} />
+  </Route>
+
+  <Route path="concerts">
+    <Route index element={<ConcertsHome />} />
+    <Route path=":city" element={<City />} />
+    <Route path="trending" element={<Trending />} />
+  </Route>
+</Routes>
+```
+
+## Nested Routes
+
+Routes can be nested inside parent routes.
+
+```tsx
+<Routes>
+  <Route path="dashboard" element={<Dashboard />}>
+    <Route index element={<Home />} />
+    <Route path="settings" element={<Settings />} />
+  </Route>
+</Routes>
+```
+
+The path of the parent is automatically included in the child, so this config creates both `"/dashboard"` and `"/dashboard/settings"` URLs.
+
+Child routes are rendered through the `<Outlet/>` in the parent route.
+
+```tsx filename=app/dashboard.tsx
+import { Outlet } from "react-router";
+
+export default function Dashboard() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      {/* will either be <Home/> or <Settings/> */}
+      <Outlet />
+    </div>
+  );
+}
+```
+
+## Layout Routes
+
+Routes _without_ a `path` create new nesting for their children, but they don't add any segments to the URL.
+
+```tsx lines=[2,9]
+<Routes>
+  <Route element={<MarketingLayout />}>
+    <Route index element={<MarketingHome />} />
+    <Route path="contact" element={<Contact />} />
+  </Route>
+
+  <Route path="projects">
+    <Route index element={<ProjectsHome />} />
+    <Route element={<ProjectsLayout />}>
+      <Route path=":pid" element={<Project />} />
+      <Route path=":pid/edit" element={<EditProject />} />
+    </Route>
+  </Route>
+</Routes>
+```
+
+## Index Routes
+
+Index routes render into their parent's `<Outlet/>` at their parent's URL (like a default child route). They are configured with the `index` prop:
+
+```tsx lines=[4,8]
+<Routes>
+  <Route path="/" element={<Root />}>
+    {/* renders into the outlet in <Root> at "/" */}
+    <Route index element={<Home />} />
+
+    <Route path="dashboard" element={<Dashboard />}>
+      {/* renders into the outlet in <Dashboard> at "/dashboard" */}
+      <Route index element={<DashboardHome />} />
+      <Route path="settings" element={<Settings />} />
+    </Route>
+  </Route>
+</Routes>
+```
+
+Note that index routes can't have children. If you're expecting that behavior, you probably want a [layout route](#layout-routes).
+
+## Route Prefixes
+
+A `<Route path>` _without_ an `element` prop adds a path prefix to its child routes, without introducing a parent layout.
+
+```tsx filename=app/routes.ts lines=[1]
+<Route path="projects">
+  <Route index element={<ProjectsHome />} />
+  <Route element={<ProjectsLayout />}>
+    <Route path=":pid" element={<Project />} />
+    <Route path=":pid/edit" element={<EditProject />} />
+  </Route>
+</Route>
+```
+
+## Dynamic Segments
+
+If a path segment starts with `:` then it becomes a "dynamic segment". When the route matches the URL, the dynamic segment will be parsed from the URL and provided as `params` to other router APIs like `useParams`.
+
+```tsx
+<Route path="teams/:teamId" element={<Team />} />
+```
+
+```tsx filename=app/team.tsx
+import { useParams } from "react-router";
+
+export default function Team() {
+  let params = useParams();
+  // params.teamId
+}
+```
+
+You can have multiple dynamic segments in one route path:
+
+```tsx
+<Route
+  path="/c/:categoryId/p/:productId"
+  element={<Product />}
+/>
+```
+
+```tsx filename=app/category-product.tsx
+import { useParams } from "react-router";
+
+export default function CategoryProduct() {
+  let { categoryId, productId } = useParams();
+  // ...
+}
+```
+
+You should ensure that all dynamic segments in a given path are unique. Otherwise, as the `params` object is populated - latter dynamic segment values will override earlier values.
+
+## Optional Segments
+
+You can make a route segment optional by adding a `?` to the end of the segment.
+
+```tsx
+<Route path=":lang?/categories" element={<Categories />} />
+```
+
+You can have optional static segments, too:
+
+```tsx
+<Route path="users/:userId/edit?" element={<User />} />
+```
+
+## Splats
+
+Also known as "catchall" and "star" segments. If a route path pattern ends with `/*` then it will match any characters following the `/`, including other `/` characters.
+
+```tsx
+<Route path="files/*" element={<File />} />
+```
+
+```tsx
+let params = useParams();
+// params["*"] will contain the remaining URL after files/
+let filePath = params["*"];
+```
+
+You can destructure the `*`, you just have to assign it a new name. A common name is `splat`:
+
+```tsx
+let { "*": splat } = useParams();
+```
+
+## Linking
+
+Link to routes from your UI with `Link` and `NavLink`
+
+```tsx
+import { NavLink, Link } from "react-router";
+
+function Header() {
+  return (
+    <nav>
+      {/* NavLink makes it easy to show active states */}
+      <NavLink
+        to="/"
+        className={({ isActive }) =>
+          isActive ? "active" : ""
+        }
+      >
+        Home
+      </NavLink>
+
+      <Link to="/concerts/salt-lake-city">Concerts</Link>
+    </nav>
+  );
+}
+```
+
+---
+
+Next: [Navigating](./navigating)