How do I validate that a string value matches a route pattern?

[xt0rted]

I have a string value and I want to check if it matches a route pattern that's registered in the router. I'm looking for a true/false response so I can then do something with it.

An example of this is does /users/123 match any of /, /dashboard, /users, /users/$id etc. that have been registered in my route tree. The value being checked could also be blah or /user/123, either way I want to know if a string of some value matches any registered route.

I've searched all over but can't find anything talking about how to check if an arbitrary value matches a route pattern. I've seen various examples of checking routes but none show how to check an unknown value against all routes.

[soosho]

router.matchRoute() is what you're looking for. It takes a pathname and returns the matched route or undefined.

import { createRouter } from '@tanstack/react-router'
import { routeTree } from './routeTree.gen'

const router = createRouter({ routeTree })

// Check if a string matches any registered route
const match = router.matchRoute('/users/123')
if (match) {
  // /users/123 matches /users/$id
}

const noMatch = router.matchRoute('/blah')
// noMatch is undefined — no registered route matches

You can also get the matched params:

const match = router.matchRoute('/users/123', { getParams: true })
// match.route — the route definition
// match.params — { id: '123' }

If you just need to check a pattern without a full router instance, there's matchPathname:

import { matchPathname } from '@tanstack/react-router'

// Check a specific path against a pattern
const result = matchPathname({ path: '/users/123', pattern: '/users/$id' })
// result — { match: true, params: { id: '123' } }

matchRoute() is the idiomatic approach since it uses the actual registered routes — no risk of mismatching against a pattern you typed wrong or forgot to register.

[xt0rted]

Thanks for the reply. The problem I'm having is the response I get back from router.matchRoute("...") is always an empty object. It doesn't matter what I pass in. Even in a newly scaffolded project I just get an empty object back for / or blah or any other value.

[soosho]

Ah, you're right — in current v1.x matchRoute() returns {} on no-match, not undefined. You can work around it:

function isValidRoute(path: string): boolean {
  const match = router.matchRoute(path)
  return match !== null && typeof match === 'object' && 'route' in match
}

Or use matchRoutes which returns [] on no-match:

router.matchRoutes('/users/123').length > 0

Cleanest approach without relying on the empty-object behavior:

import { matchPathname } from '@tanstack/react-router'

function pathMatchesAnyRoute(path: string): boolean {
  return Object.values(router.routesById).some(route => {
    if (!route.options.path) return false
    return matchPathname({ path, pattern: route.options.path }).match
  })
}

[DucMinhNe]

Use router.matchRoutes(pathname) and check whether the leaf match is a real route (not just the root). I tested this on @tanstack/react-router@1.170.15.

function pathMatchesAnyRoute(router, path: string): boolean {
  const matches = router.matchRoutes(path)
  const leaf = matches[matches.length - 1]
  return !!leaf && leaf.routeId !== '__root__'
}

With routes /, /dashboard, /users, /users/$id:

pathMatchesAnyRoute(router, '/users/123') // true  -> matches /users/$id
pathMatchesAnyRoute(router, '/users')     // true
pathMatchesAnyRoute(router, '/dashboard') // true
pathMatchesAnyRoute(router, '/blah')      // false
pathMatchesAnyRoute(router, '/user/123')  // false (typo'd segment)

Why not matchRoute()

router.matchRoute() is the wrong primitive here. It takes a location object ({ to }), not a bare pathname, and it matches relative to the router's current location with includeSearch: true by default — so it answers "is the router currently at/under this route," not "does this arbitrary string match any registered route." In my test, router.matchRoute({ to: '/users/123' }) returned false while the router sat at /, even though that path is perfectly valid. It returns false on no-match (not undefined), and {} for a param-less match, so it's also awkward to truth-test.

Why you can't just use .length

matchRoutes() always includes the __root__ match, so the array is never empty — /blah still returns [{ routeId: '__root__', ... }] (length 1). That's why the check has to be "is the leaf something other than __root__," not length > 0.

One gotcha — exactness

Because there's no catch-all/error route here, a too-long path like /users/123/extra fuzzy-falls-back to /users/$id as the leaf (with a ** splat param), so the helper above reports true. If you need a strict match, also reject leaves that captured a splat:

function pathMatchesExact(router, path: string): boolean {
  const matches = router.matchRoutes(path)
  const leaf = matches[matches.length - 1]
  return !!leaf && leaf.routeId !== '__root__' && leaf.params?.['**'] === undefined
}

Call this on your real router instance (the one you pass to <RouterProvider>). matchRoutes reads the processed route tree off the live router, so it works regardless of where the user has currently navigated.