Skip to content

Commit af011ad

Browse files
match params
1 parent 7fa0f39 commit af011ad

32 files changed

Lines changed: 1505 additions & 1142 deletions

‎.changeset/clean-routes-match.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
'@tanstack/router-core': minor
3+
'@tanstack/react-router': minor
4+
'@tanstack/solid-router': minor
5+
'@tanstack/vue-router': minor
6+
---
7+
8+
Replace the experimental `skipRouteOnParseError` route option with `params.match` and `params.matchPriority` for route selection. `params.match` now gates matching with raw path params, while `params.parse` remains responsible for typed params and `params.stringify` remains responsible for URL generation.

‎docs/router/api/router/RouteOptionsType.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,19 @@ The `RouteOptions` type accepts an object with the following properties:
8383
- Optional
8484
- A function that will be called when this route is matched and passed the raw params from the current location and return valid parsed params. If this function throws, the route will be put into an error state and the error will be thrown during render. If this function does not throw, its return value will be used as the route's params and the return type will be inferred into the rest of the router.
8585

86+
### `params.match` method (experimental)
87+
88+
- Type: `(rawParams: Record<string, string>) => boolean`
89+
- Optional
90+
- A function that will be called during route matching and passed the raw params from the current location. If this function returns `false` or throws, the route is skipped and matching continues to other candidate routes. If this function returns `true`, the route is matched. Use `params.parse` to transform matching raw params into typed route params.
91+
92+
### `params.matchPriority` property (experimental)
93+
94+
- Type: `number`
95+
- Optional
96+
- Defaults to `0`
97+
- A tie-breaker for routes with `params.match` that would otherwise have the same matching priority. Higher numbers are tried first.
98+
8699
### `params.stringify` method
87100

88101
- Type: `(params: TParams) => Record<string, string>`
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
node_modules
2+
.DS_Store
3+
dist
4+
dist-hash
5+
dist-ssr
6+
*.local
7+
8+
/test-results/
9+
/playwright-report/
10+
/blob-report/
11+
/playwright/.cache/
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
6+
<title>Match Params</title>
7+
</head>
8+
<body>
9+
<div id="app"></div>
10+
<script type="module" src="/src/main.tsx"></script>
11+
</body>
12+
</html>
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"name": "tanstack-router-e2e-react-match-params",
3+
"private": true,
4+
"type": "module",
5+
"scripts": {
6+
"dev": "vite --port 3000",
7+
"build": "vite build && tsc --noEmit",
8+
"preview": "vite preview",
9+
"test:e2e": "rm -rf port*.txt; playwright test --project=chromium"
10+
},
11+
"dependencies": {
12+
"@tanstack/react-router": "workspace:^",
13+
"react": "^19.0.0",
14+
"react-dom": "^19.0.0"
15+
},
16+
"devDependencies": {
17+
"@playwright/test": "^1.50.1",
18+
"@tanstack/router-e2e-utils": "workspace:^",
19+
"@types/react": "^19.0.8",
20+
"@types/react-dom": "^19.0.3",
21+
"vite": "^8.0.0"
22+
}
23+
}
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
import { defineConfig, devices } from '@playwright/test'
2+
import { getTestServerPort } from '@tanstack/router-e2e-utils'
3+
import packageJson from './package.json' with { type: 'json' }
4+
5+
const PORT = await getTestServerPort(packageJson.name)
6+
const baseURL = `http://localhost:${PORT}`
7+
8+
export default defineConfig({
9+
testDir: './tests',
10+
workers: 1,
11+
reporter: [['line']],
12+
use: {
13+
baseURL,
14+
},
15+
webServer: {
16+
command: `pnpm build && pnpm preview --port ${PORT}`,
17+
url: baseURL,
18+
reuseExistingServer: !process.env.CI,
19+
stdout: 'pipe',
20+
},
21+
projects: [
22+
{
23+
name: 'chromium',
24+
use: { ...devices['Desktop Chrome'] },
25+
},
26+
],
27+
})
Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
import ReactDOM from 'react-dom/client'
2+
import {
3+
Link,
4+
Outlet,
5+
RouterProvider,
6+
createRootRoute,
7+
createRoute,
8+
createRouter,
9+
} from '@tanstack/react-router'
10+
11+
const rootRoute = createRootRoute({
12+
component: RootComponent,
13+
notFoundComponent: () => <h1 data-testid="not-found">Root not found</h1>,
14+
})
15+
16+
function RootComponent() {
17+
return (
18+
<>
19+
<nav aria-label="Main navigation">
20+
<Link
21+
data-testid="match-en-link"
22+
to="/match/{$language}"
23+
params={{ language: 'en-US' }}
24+
>
25+
Match EN
26+
</Link>{' '}
27+
<Link
28+
data-testid="numeric-user-link"
29+
to="/users/$userId"
30+
params={{ userId: 456 }}
31+
>
32+
Numeric user
33+
</Link>{' '}
34+
<Link
35+
data-testid="username-link"
36+
to="/users/$username"
37+
params={{ username: 'alice' }}
38+
>
39+
Username
40+
</Link>{' '}
41+
<Link
42+
data-testid="org-settings-link"
43+
to="/orgs/$orgId/settings"
44+
params={{ orgId: 42 }}
45+
>
46+
Org settings
47+
</Link>{' '}
48+
<Link
49+
data-testid="ambiguous-dollar-link"
50+
to="/ambiguous/$value"
51+
params={{ value: 'alpha' }}
52+
>
53+
Ambiguous dollar
54+
</Link>{' '}
55+
<Link
56+
data-testid="ambiguous-curly-link"
57+
to="/ambiguous/{$value}"
58+
params={{ value: 'alpha' }}
59+
>
60+
Ambiguous curly
61+
</Link>
62+
</nav>
63+
<Outlet />
64+
</>
65+
)
66+
}
67+
68+
const indexRoute = createRoute({
69+
getParentRoute: () => rootRoute,
70+
path: '/',
71+
component: () => <h1>Match params e2e</h1>,
72+
})
73+
74+
const matchLanguageRoute = createRoute({
75+
getParentRoute: () => rootRoute,
76+
path: '/match/{$language}',
77+
params: {
78+
parse: ({ language }) => {
79+
if (language === 'en') return { language: 'en-US' as const }
80+
if (language === 'pl') return { language: 'pl-PL' as const }
81+
return false
82+
},
83+
stringify: ({ language }) => {
84+
if (language === 'en-US') return { language: 'en' }
85+
if (language === 'pl-PL') return { language: 'pl' }
86+
return { language }
87+
},
88+
},
89+
component: MatchLanguageComponent,
90+
})
91+
92+
function MatchLanguageComponent() {
93+
const params = matchLanguageRoute.useParams()
94+
return <h1 data-testid="match-language">Match language {params.language}</h1>
95+
}
96+
97+
const usersRoute = createRoute({
98+
getParentRoute: () => rootRoute,
99+
path: '/users',
100+
})
101+
102+
const numericUserRoute = createRoute({
103+
getParentRoute: () => usersRoute,
104+
path: '$userId',
105+
params: {
106+
parse: ({ userId }) => {
107+
const parsed = Number(userId)
108+
if (!Number.isInteger(parsed)) return false
109+
return { userId: parsed }
110+
},
111+
stringify: ({ userId }) => ({ userId: String(userId) }),
112+
},
113+
component: NumericUserComponent,
114+
})
115+
116+
function NumericUserComponent() {
117+
const params = numericUserRoute.useParams()
118+
return <h1 data-testid="numeric-user">Numeric user {params.userId}</h1>
119+
}
120+
121+
const usernameRoute = createRoute({
122+
getParentRoute: () => usersRoute,
123+
path: '$username',
124+
component: UsernameComponent,
125+
})
126+
127+
function UsernameComponent() {
128+
const params = usernameRoute.useParams()
129+
return <h1 data-testid="username">Username {params.username}</h1>
130+
}
131+
132+
const numericOrgRoute = createRoute({
133+
getParentRoute: () => rootRoute,
134+
path: '/orgs/$orgId',
135+
params: {
136+
parse: ({ orgId }) => {
137+
const parsed = Number(orgId)
138+
if (!Number.isInteger(parsed)) return false
139+
return { orgId: parsed }
140+
},
141+
stringify: ({ orgId }) => ({ orgId: String(orgId) }),
142+
},
143+
})
144+
145+
const orgSettingsRoute = createRoute({
146+
getParentRoute: () => numericOrgRoute,
147+
path: 'settings',
148+
component: OrgSettingsComponent,
149+
})
150+
151+
function OrgSettingsComponent() {
152+
const params = orgSettingsRoute.useParams()
153+
return <h1 data-testid="org-settings">Org settings {params.orgId}</h1>
154+
}
155+
156+
const orgAboutRoute = createRoute({
157+
getParentRoute: () => rootRoute,
158+
path: '/orgs/$slug/about',
159+
component: OrgAboutComponent,
160+
})
161+
162+
function OrgAboutComponent() {
163+
const params = orgAboutRoute.useParams()
164+
return <h1 data-testid="org-about">Org about {params.slug}</h1>
165+
}
166+
167+
const ambiguousRoute = createRoute({
168+
getParentRoute: () => rootRoute,
169+
path: '/ambiguous',
170+
})
171+
172+
const ambiguousDollarRoute = createRoute({
173+
getParentRoute: () => ambiguousRoute,
174+
path: '$value',
175+
params: {
176+
parse: ({ value }) => {
177+
if (!value.startsWith('dollar-')) return false
178+
return { value: value.slice(7) }
179+
},
180+
stringify: ({ value }) => ({ value: `dollar-${value}` }),
181+
},
182+
component: AmbiguousDollarComponent,
183+
})
184+
185+
function AmbiguousDollarComponent() {
186+
const params = ambiguousDollarRoute.useParams()
187+
return <h1 data-testid="ambiguous-dollar">Dollar {params.value}</h1>
188+
}
189+
190+
const ambiguousCurlyRoute = createRoute({
191+
getParentRoute: () => ambiguousRoute,
192+
path: '{$value}',
193+
params: {
194+
parse: ({ value }) => {
195+
if (!value.startsWith('curly-')) return false
196+
return { value: value.slice(6) }
197+
},
198+
stringify: ({ value }) => ({ value: `curly-${value}` }),
199+
},
200+
component: AmbiguousCurlyComponent,
201+
})
202+
203+
function AmbiguousCurlyComponent() {
204+
const params = ambiguousCurlyRoute.useParams()
205+
return <h1 data-testid="ambiguous-curly">Curly {params.value}</h1>
206+
}
207+
208+
const routeTree = rootRoute.addChildren([
209+
indexRoute,
210+
matchLanguageRoute,
211+
usersRoute.addChildren([numericUserRoute, usernameRoute]),
212+
numericOrgRoute.addChildren([orgSettingsRoute]),
213+
orgAboutRoute,
214+
ambiguousRoute.addChildren([ambiguousDollarRoute, ambiguousCurlyRoute]),
215+
])
216+
217+
const router = createRouter({ routeTree })
218+
219+
declare module '@tanstack/react-router' {
220+
interface Register {
221+
router: typeof router
222+
}
223+
}
224+
225+
const rootElement = document.getElementById('app')!
226+
227+
if (!rootElement.innerHTML) {
228+
ReactDOM.createRoot(rootElement).render(<RouterProvider router={router} />)
229+
}

0 commit comments

Comments
 (0)