Why does the useParams hook use the route's id instead of its path?

[bac1lla]

I'm using code-based routing with nested routes:

export const groupItemRoutePath = '/path';

const groupRoute = createRoute({id: 'id', getParentRoute: () => rootRoute});
const groupItemRoute = createRoute({
  path: groupItemRoutePath,
  getParentRoute: () => groupRoute,
});

rootRoute.addChildren([groupRoute.addChildren([groupItemRoute])]);

Calling useParams in a component using the path will throw an error:

useParams({from: groupItemRoutePath});

useParams internally uses the route's id, not its path. When using nested routes, the id is generated based on the parent route's id and the child route's path. Because of this, it becomes impossible to reuse route path constants—you have to either import the route and use its id or search through router.routesByPath. Is this the expected behavior? It would be good if this were mentioned in the documentation

[travisbreaks]

In code-based routing, the from option in useParams expects the route's full route ID, not its URL path. When a pathless parent has a custom id (e.g., id: 'id'), the child route's full ID becomes a combination of the parent ID and the child path. For your setup the child route ID would be 'id/path', not '/path'.

The fix: reference the route object directly instead of passing a string.

const params = useParams({ from: groupItemRoute.id })

This way TypeScript infers the correct params type from the route definition, and you don't have to guess the internal ID format.

[x-tahosin]

This is intentional and the docs really should call it out — route paths aren't unique (you can have layout routes / parallel routes / pathless routes that share the same path segment), so the router needs a stable identifier to look up params, and that identifier is the route's id.

The cleaner pattern that sidesteps the whole problem is to call useParams off the Route definition itself rather than passing from by hand:

// in your route file
export const groupItemRoute = createRoute({
  path: groupItemRoutePath,
  getParentRoute: () => groupRoute,
});

// in a child component
import { groupItemRoute } from '../routes/groupItem.route';
const params = groupItemRoute.useParams();   // fully typed, no string at all

Route.useParams() is generated for you by createRoute, knows its own id, and returns a typed Params shape with no string-passing. Same goes for useSearch, useLoaderData, useNavigate, useMatch — they all have a Route.use*() companion that's the recommended way to read route-scoped state.

If you really do want to pass from (e.g. you're in a generic component that's used under multiple routes), the value to pass is the resolved id. The router exposes that via the registered routes:

// inside a component that knows it's mounted under groupItemRoute
useParams({ from: groupItemRoute.id });
// or, if you're in code-based routing, the literal generated id:
useParams({ from: '/id/path' });    // parent id ('id') + child path

The id-generation rule for code-based routing is: parent.id + ('/' + child.path). So in your example with groupRoute.id = 'id' and groupItemRoute.path = '/path', the resolved id is '/id/path'. (For root children, it's '/' + child.path.)

For file-based routing the route IDs are the file paths, which keeps the literal-equals-path intuition. Code-based gives you more flexibility but yes, you pay for it with the id-vs-path divergence.

Why I'd push for Route.useParams() even if useParams({ from }) works

• No string to keep in sync if you rename a route — you re-export the Route, the type follows.
• The CLI / dev tools can show "this component depends on Route X" — useful in big router trees.
• Route.useParams() will narrow the union on conditional renders better, because it's not a generic call with a string-to-type lookup.

So your docs request is exactly right — and "use Route.useParams() instead of useParams({ from })" is what should be at the top of the params docs. (Worth opening a docs PR; the maintainers have merged similar clarifications quickly in the past.)