useMatches missing generic

[y-nk]

Reproduction

Try to write a hook to generate breadcrumbs using useMatches such as:

import { UIMatch, useMatches } from 'react-router'

type BreadcrumbMatch = UIMatch<unknown, { breadcrumb: string }>

export function useBreadcrumbs(): { title: string; path?: string }[] {
  return useMatches()
    .filter((m): m is BreadcrumbMatch => !!m.handle?.breadcrumb)
    .map((match, i, a) => ({
      path: i < a.length - 1 ? match.pathname : undefined,
      title: match.handle.breadcrumb,
    }))
}

There will be a typescript error because handle is defaulted to unknown, which forces us to write:

type MaybeBreadcrumbMatch = UIMatch<unknown, { breadcrumb?: string }>

export function useBreadcrumbs(): { title: string; path?: string }[] {
  return (useMatches() as MaybeBreadcrumbMatch[])
    .filter((m): m is BreadcrumbMatch => !!m.handle?.breadcrumb)

System Info

Binaries:
    Node: 24.2.0
    pnpm: 10.13.1

(The rest is irrelevant to my issue.)

Used Package Manager

npm

Expected Behavior

There should be a way to pass the generics of returned UIMatch from the useMatches() hook. Maybe a useMatches<A = unknown, B = unknown>(): UIMatch<A, B>[] would be non breaking and appropriate.

Actual Behavior

There's no way to type correctly without making use of as because the default type of handle is unknown

[brophdawg11]

Converted this request from an issue to a discussion to go through our Open Governance process.

[brophdawg11]

The approach in #14218 doesn't work because that types every match with the same Data/Handle generic types, which is incorrect. The recommended approach right now is to cast each matches to UIMatch<Data, Handle> with the proper types for their specific data and handle.

[y-nk]

how is a force-cast a recommended approach? proposed fix doesn't harm as it's fully opt-in, so it's a conscious move to type as such. default remains unchanged so it's 100% leaving more control to users knowingly writing this for a specific purpose.

[brophdawg11]

All your PR does is hide the force-cast from the user - there is no actual type-safety being added. Nothing stops you from changing the shape of the data or the handle on your routes - and then your useMatches<Data, Handle> is wrong and you are no longer able to catch bugs at build-time. We prefer that type of force cast be explicit and visible to the user, not hidden underneath the framework layer.

[y-nk]

i'd rather have type safety as well but the cost of implementing this is much higher and complex. that doesn't mean we can't have nothing. if as is as good, then it'd be nicer to have an integrated way which is eventually future proof.

[brophdawg11]

You don't have nothing, you have the typegen in framework mode: https://stackblitz.com/edit/github-ofxolbsb?file=app%2Froutes%2F_index.tsx.

And in data/declarative mode you have matches[i] as UIMatch<Data, Handle>. That is the recommended solution we decided on after we thought about the complexity of typing matches. That is the proper level of granularity because every route can have a different type for data and handle.