Consolidate route data access with new type-safe hook: useRoute

[pcattori]

Supersedes: #13896 , #10761
Relates to: #9854 , #13961

PR: #14407

---

New useRoute hook for accessing data from specific routes

For example, let's say you have an admin route somewhere in your app and you want any child routes of admin to all have access to the loaderData and actionData from admin.

// app/routes/admin.tsx
import { Outlet } from "react-router";

export const loader = () => ({ message: "Hello, loader!" });

export const action = () => ({ count: 1 });

export default function Component() {
  return (
    <div>
      {/* ... */}
      <Outlet />
      {/* ... */}
    </div>
  );
}

You might even want to create a reusable widget that all of the routes nested under admin could use:

import { unstable_useRoute as useRoute } from "react-router";

export function AdminWidget() {
  // How to get `message` and `count` from `admin` route?
}

In framework mode, useRoute knows all your app's routes and gives you TS errors when invalid route IDs are passed in:

export function AdminWidget() {
  const admin = useRoute("routes/dmin");
  //                      ^^^^^^^^^^^
}

useRoute returns undefined if the route is not part of the current page:

export function AdminWidget() {
  const admin = useRoute("routes/admin");
  if (!admin) {
    throw new Error(`AdminWidget used outside of "routes/admin"`);
  }
}

Note: the root route is the exception since it is guaranteed to be part of the current page.
As a result, useRoute never returns undefined for root.

loaderData and actionData are marked as optional since they could be accessed before the action is triggered or after the loader threw an error:

export function AdminWidget() {
  const admin = useRoute("routes/admin");
  if (!admin) {
    throw new Error(`AdminWidget used outside of "routes/admin"`);
  }
  const { loaderData, actionData } = admin;
  console.log(loaderData);
  //          ^? { message: string } | undefined
  console.log(actionData);
  //          ^? { count: number } | undefined
}

If instead of a specific route, you wanted access to the current route's loaderData and actionData, you can call useRoute without arguments:

export function AdminWidget() {
  const currentRoute = useRoute();
  currentRoute.loaderData;
  currentRoute.actionData;
}

This usage is equivalent to calling useLoaderData and useActionData, but consolidates all route data access into one hook: useRoute.

Note: when calling useRoute() (without a route ID), TS has no way to know which route is the current route.
As a result, loaderData and actionData are typed as unknown.
If you want more type-safety, you can either narrow the type yourself with something like zod or you can refactor your app to pass down typed props to your AdminWidget:

export function AdminWidget({
  message,
  count,
}: {
  message: string;
  count: number;
}) {
  /* ... */
}

Future work

• Add typed handle to result returned by useRoute (Can we make the `handle` property of RouteObject an interface? #13961)

[nathggns]

Have you considered making it possible to automatically throw if used by a component not rendered on a particular route - so the consuming component doesn’t need to handle that itself? I can see why making it nullable is more flexible (like React’s use context), but I almost always need to make my own context specific hook that throws if used incorrectly and that would defeat much of the benefit of this I expect if you needed to do that (as otherwise you could just import that route’s typegen file where you define the wrapper, which is close to what we’re doing already).

[rossipedia]

Maybe a useRoute(routeId, strict) overload that would throw?

[sergiodxa]

Making it throw would prevent its usage on root Layout component or any route ErrorBoundary

I think it's easy to wrap in a useStrictRoute hook that throws if the return value is null

If it's easy to do ok user land then it should remain on user land IMO

[nathggns]

I don’t think “if it’s easy to do user land, it should be done user land” is coming to terms with the amount of code that is written by AI these days. They won’t write a hook to do this, they’ll just proliferate checks throughout your components and/or use ! to ignore the type errors. It’s also reducing the opportunity for the library to push people into the “river of success” with its APIs.

The issue you state is a real one and the API needs to exist for optional access because of it. I just think we need a built in strict access API too, which things like context7/llms.txt etc would encourage AIs to use.