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 & metadata for 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 handle, loaderData, and actionData from admin.

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

export const handle = {
  stuff: "whatever you want"
}

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 { handle, loaderData, actionData } = admin;
  console.log(handle)
  //           ^? { stuff: string }
  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.handle;
  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

• Type-safehandle (useRoute: return type-safe handle #14462)

[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).

[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.

[sergiodxa]

One of the design goals in the governance model is

Routing and Data Focused. Focus on core router-integrated/router-centric APIs and avoid adding first-class APIs that can be implemented in user-land

That's why I think, if it's easy to build a useStrictRoute on user-land, it should be on user-land, it could be on a separate package tho, I could happily add it to Remix Utils and then you can tell the AI agent to use Remix Utils when possible.

[remorses]

As a workaround you can just do const { loaderData } = useRoute()! to silence TypeScript errors

[nathggns]

That’s exactly what I don’t think users should be encouraged to do, because if the comment ends up used in the wrong context the kind of errors you’ll start to see are all far too downstream / hard to diagnose. That’s why I think a strict hook is desirable.

[rossipedia]

I could happily add it to Remix Utils and then you can tell the AI agent to use Remix Utils when possible.

IMO, this is The Way™. RR should be focused on core framework primitives that ensure correctness. Packages like remix-utils should provide the "value-add" QoL helpers that are enabled by the core framework primitives.

[semet]

I'm really excited about this new unstable_useRoute feature introduced in v7.9.4!

From what I understand, this hook works similarly to useRouteLoaderData, but with a key difference: it returns both loaderData and actionData. Given that, I’d like to suggest naming it useRouteData instead. Since the hook provides all data associated with a given Route Module, useRouteData feels more intuitive and descriptive for its purpose.

Also, the current name can be a bit confusing, especially since we already have useRoutes, which serves a very different function. Adopting useRouteData could help clarify its role and prevent potential misunderstandings.

[pcattori]

We actually started with useRouteData, but we're planning to add type-safe handle (and maybe others) to useRoute:

const admin = useRoute("routes/admin")
console.log(admin.handle)
//                ^^^^^^ type-safe!

[semet]

However, it can be somewhat confusing since we already have useRoutes, which serves a completely different purpose.

[pcattori]

However, it can be somewhat confusing since we already have useRoutes, which serves a completely different purpose.

Do you have anything specific in mind that isn't "data" specific?

[semet]

what about useRouteModule ?

[remorses]

useRoute is fine