fix(react-router): Link isActive on competing optional segment routes

[Sheraff]

Summary

Fixes param inheritance when building locations so links and navigations only inherit current params when explicitly requested.

Problem

Links to routes with optional params could accidentally reuse params from the current location when params was omitted. This caused competing optional segment links like /foo/bar and /bar to both resolve as active from /foo/bar.

// Current location: /foo/bar

<Link to="/{-$foo}/bar" params={{ foo: 'foo' }}>
  To /foo/bar
</Link>

<Link to="/{-$foo}/bar">
  To /bar
</Link>

Before this fix, the second link inherited { foo: 'foo' } from the current route even though it did not pass params, so it built /foo/bar instead of /bar and incorrectly became active alongside the first link.

Changes

• Updated buildLocation param inheritance rules in router-core.
• Added core coverage for omitted params, object params, params: true, and explicit from.
• Added React/Solid/Vue regression coverage for competing optional segment links.
• Updated React/Solid/Vue tests to make intended param inheritance explicit with params: true or from.

TODO

We should also change the types, so something like this would be allowed: <Link to="/{-$foo}/bar"> (i.e. no required for params since $foo is optional)

Summary by CodeRabbit

• Bug Fixes

  • Refined parameter inheritance when navigating so omitted or optional params behave correctly depending on whether an explicit source route is provided.
  • Fixed Link active-state detection (aria-current) when multiple routes compete via optional segments.

• Tests

  • Added regression tests for Link active-state across frameworks covering competing optional routes.
  • Expanded navigation tests to cover from-route semantics and optional-param carryover behavior.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Refactors parameter inheritance in buildLocation to depend on explicit from, dest.params values/functions, and to absoluteness; updates navigation tests to pass explicit from and use params: true; adds Link regression tests across adapters; expands build-location tests covering inheritance semantics.

Changes

Cohort / File(s)	Summary
Link Active-State Regression Tests packages/react-router/tests/link.test.tsx, packages/solid-router/tests/link.test.tsx, packages/vue-router/tests/link.test.tsx	Adds regression tests validating Link active-state (aria-current="page") when routes compete via an optional segment (e.g., /{-$foo}/bar), ensuring only the matching link remains current after navigation.
Navigate Test Updates packages/react-router/tests/navigate.test.tsx, packages/solid-router/tests/navigate.test.tsx, packages/vue-router/tests/navigate.test.tsx	Modifies navigation tests to supply an explicit from route pattern for object-syntax param updates and changes optional-parameter carryover tests to use params: true instead of params: {} (and updates test descriptions).
Core Parameter Resolution Logic packages/router-core/src/router.ts	Rewrites buildLocation param derivation: introduces an inheritParams determination (based on dest.params, functions, explicit from, and to absoluteness) and three resolution branches (pure inherit, functional updater merge, direct merge when non-inheriting).
Parameter Resolution Test Coverage packages/router-core/tests/build-location.test.ts	Adds tests asserting that params do not inherit from current route when from is absent, but do merge/resolve correctly when from is provided; covers required and optional params and object params behavior.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐇 I hop through routes with careful cheer,
Params I carry, sometimes far, sometimes near,
From context clear or left behind,
Each link now knows the path to find—
A nimble rabbit, routing without fear. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(react-router): Link isActive on competing optional segment routes' directly addresses the main bug being fixed across the entire changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-react-router-link-active-optional-segment-competition

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 6e79fff

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	❌ Failed	6m 49s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	34s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-05-01 13:58:42 UTC

[github-actions]

🚀 Changeset Version Preview

No changeset entries found. Merging this PR will not cause a version bump for any packages.

[pkg-pr-new]

More templates

• tanstack-router-solid-example-authenticated-routes
• tanstack-router-solid-example-authenticated-routes-firebase
• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-default-search-params
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-basic-virtual-file-based
• tanstack-router-solid-example-basic-virtual-inside-file-based
• tanstack-router-solid-example-deferred-data
• tanstack-router-solid-i18n-paraglide
• tanstack-router-solid-example-kitchen-sink
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-large-file-based
• tanstack-router-solid-example-location-masking
• tanstack-router-solid-example-navigation-blocking
• tanstack-router-solid-example-quickstart
• tanstack-router-solid-example-quickstart-esbuild-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-router-solid-example-quickstart-rspack-file-based
• tanstack-router-solid-example-quickstart-webpack-file-based
• @tanstack/router-solid-mono-simple
• router-solid-mono-simple-lazy
• router-solid-monorepo-solid-query
• tanstack-router-solid-example-scroll-restoration
• tanstack-solid-router-search-validator-adapters
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-authjs
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-bun-hosting
• tanstack-solid-start-example-convex-better-auth
• tanstack-solid-start-example-counter
• tanstack-solid-start-i18n-paraglide
• tanstack-solid-start-example-large
• tanstack-solid-start-streaming-data-from-server-functions
• tanstack-solid-start-example-supabase-basic
• tanstack-solid-start-tailwind-v4
• tanstack-router-solid-example-view-transitions
• tanstack-router-solid-example-with-framer-motion
• tanstack-router-solid-example-with-trpc
• tanstack-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc
• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-router-react-example-basic-authjs
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-example-rscs
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query

@tanstack/arktype-adapter

npm i https://pkg.pr.new/@tanstack/arktype-adapter@7303

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/@tanstack/eslint-plugin-router@7303

@tanstack/eslint-plugin-start

npm i https://pkg.pr.new/@tanstack/eslint-plugin-start@7303

@tanstack/history

npm i https://pkg.pr.new/@tanstack/history@7303

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/@tanstack/nitro-v2-vite-plugin@7303

@tanstack/react-router

npm i https://pkg.pr.new/@tanstack/react-router@7303

@tanstack/react-router-devtools

npm i https://pkg.pr.new/@tanstack/react-router-devtools@7303

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/@tanstack/react-router-ssr-query@7303

@tanstack/react-start

npm i https://pkg.pr.new/@tanstack/react-start@7303

@tanstack/react-start-client

npm i https://pkg.pr.new/@tanstack/react-start-client@7303

@tanstack/react-start-rsc

npm i https://pkg.pr.new/@tanstack/react-start-rsc@7303

@tanstack/react-start-server

npm i https://pkg.pr.new/@tanstack/react-start-server@7303

@tanstack/router-cli

npm i https://pkg.pr.new/@tanstack/router-cli@7303

@tanstack/router-core

npm i https://pkg.pr.new/@tanstack/router-core@7303

@tanstack/router-devtools

npm i https://pkg.pr.new/@tanstack/router-devtools@7303

@tanstack/router-devtools-core

npm i https://pkg.pr.new/@tanstack/router-devtools-core@7303

@tanstack/router-generator

npm i https://pkg.pr.new/@tanstack/router-generator@7303

@tanstack/router-plugin

npm i https://pkg.pr.new/@tanstack/router-plugin@7303

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/@tanstack/router-ssr-query-core@7303

@tanstack/router-utils

npm i https://pkg.pr.new/@tanstack/router-utils@7303

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/@tanstack/router-vite-plugin@7303

@tanstack/solid-router

npm i https://pkg.pr.new/@tanstack/solid-router@7303

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/@tanstack/solid-router-devtools@7303

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/@tanstack/solid-router-ssr-query@7303

@tanstack/solid-start

npm i https://pkg.pr.new/@tanstack/solid-start@7303

@tanstack/solid-start-client

npm i https://pkg.pr.new/@tanstack/solid-start-client@7303

@tanstack/solid-start-server

npm i https://pkg.pr.new/@tanstack/solid-start-server@7303

@tanstack/start-client-core

npm i https://pkg.pr.new/@tanstack/start-client-core@7303

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/@tanstack/start-fn-stubs@7303

@tanstack/start-plugin-core

npm i https://pkg.pr.new/@tanstack/start-plugin-core@7303

@tanstack/start-server-core

npm i https://pkg.pr.new/@tanstack/start-server-core@7303

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/@tanstack/start-static-server-functions@7303

@tanstack/start-storage-context

npm i https://pkg.pr.new/@tanstack/start-storage-context@7303

@tanstack/valibot-adapter

npm i https://pkg.pr.new/@tanstack/valibot-adapter@7303

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/@tanstack/virtual-file-routes@7303

@tanstack/vue-router

npm i https://pkg.pr.new/@tanstack/vue-router@7303

@tanstack/vue-router-devtools

npm i https://pkg.pr.new/@tanstack/vue-router-devtools@7303

@tanstack/vue-router-ssr-query

npm i https://pkg.pr.new/@tanstack/vue-router-ssr-query@7303

@tanstack/vue-start

npm i https://pkg.pr.new/@tanstack/vue-start@7303

@tanstack/vue-start-client

npm i https://pkg.pr.new/@tanstack/vue-start-client@7303

@tanstack/vue-start-server

npm i https://pkg.pr.new/@tanstack/vue-start-server@7303

@tanstack/zod-adapter

npm i https://pkg.pr.new/@tanstack/zod-adapter@7303

commit: 6e79fff

[github-actions]

Bundle Size Benchmarks

• Commit: 8b9ea22b5b1a
• Measured at: 2026-05-01T13:52:54.901Z
• Baseline source: history:ae453b78624c
• Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Raw	Brotli	Trend
react-router.minimal	87.22 KiB	+73 B (+0.08%)	274.05 KiB	75.84 KiB	█████▁▁▁▁▁▁▄
react-router.full	90.71 KiB	+30 B (+0.03%)	285.56 KiB	78.87 KiB	█████▁▁▁▁▁▁▃
solid-router.minimal	35.46 KiB	+77 B (+0.21%)	106.35 KiB	31.92 KiB	█████▁▁▁▁▁▁▄
solid-router.full	40.17 KiB	+69 B (+0.17%)	120.56 KiB	36.07 KiB	█████▁▁▁▁▁▁▄
vue-router.minimal	53.22 KiB	+72 B (+0.13%)	151.50 KiB	47.86 KiB	█████▁▁▁▁▁▁▄
vue-router.full	58.36 KiB	+85 B (+0.14%)	167.68 KiB	52.21 KiB	█████▁▁▁▁▁▁▅
react-start.minimal	101.83 KiB	+70 B (+0.07%)	322.21 KiB	88.12 KiB	█████▁▁▁▁▁▁▄
react-start.full	105.26 KiB	+78 B (+0.07%)	332.54 KiB	91.02 KiB	█████▁▁▁▁▁▁▄
react-start.rsbuild.minimal	99.37 KiB	+40 B (+0.04%)	316.57 KiB	85.45 KiB	███▂▂▁▁▁▁▁▁▁
react-start.rsbuild.full	102.68 KiB	+50 B (+0.05%)	327.00 KiB	88.32 KiB	███▂▂▁▁▁▁▁▁▁
solid-start.minimal	49.47 KiB	+73 B (+0.14%)	152.18 KiB	43.65 KiB	█████▁▁▁▁▁▁▄
solid-start.full	55.27 KiB	+80 B (+0.14%)	169.08 KiB	48.67 KiB	█████▁▁▁▁▁▁▅

Trend sparkline is historical gzip bytes ending with this PR measurement; lower is better.

[codspeed-hq]

Merging this PR will not alter performance

✅ 5 untouched benchmarks
⏩ 1 skipped benchmark¹

---

_{Comparing fix-react-router-link-active-optional-segment-competition (6e79fff) with main (ae453b7)²}

Footnotes

1. 1 benchmark was skipped, so the baseline result was used instead. If it was deleted from the codebase, click here and archive it to remove it from the performance reports. ↩

2. No successful run was found on main (8b9ea22) during the generation of this report, so ae453b7 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/router-core/src/router.ts`:
- Around line 1863-1875: The bug is that baseParams is seeded from the active
match's params (fromParams/lightweightResult.params) even when dest.from is
specified; instead, when dest.from exists compute inherited params by
re-matching currentLocation.pathname against dest.from (using the same route
matching helper used elsewhere in router.ts) to produce the correct params
object before applying dest.params/functionalUpdate; update the logic in the
inheritParams/baseParams/nextParams block (referencing inheritParams,
baseParams, nextParams, dest.from, fromParams, functionalUpdate,
currentLocation.pathname) to use those re-matched params and add a regression
test that exercises competing optional-segment routes (e.g. /{-$foo}/bar vs
/foo/{-$bar}) to verify href and isActive behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 21e54d3f-c346-4943-834b-f3dc6a5ac203

📥 Commits

Reviewing files that changed from the base of the PR and between a5f8ef0 and 1beb4b6.

📒 Files selected for processing (11)

• packages/react-router/tests/link.test.tsx
• packages/react-router/tests/navigate.test.tsx
• packages/react-router/tests/useNavigate.test.tsx
• packages/router-core/src/router.ts
• packages/router-core/tests/build-location.test.ts
• packages/solid-router/tests/link.test.tsx
• packages/solid-router/tests/navigate.test.tsx
• packages/solid-router/tests/useNavigate.test.tsx
• packages/vue-router/tests/link.test.tsx
• packages/vue-router/tests/navigate.test.tsx
• packages/vue-router/tests/useNavigate.test.tsx

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/react-router/tests/link.test.tsx

[nx-cloud]

Nx Cloud has identified a possible root cause for your failed CI:

We classified this failure as an environment state issue rather than a code change. The tanstack-react-start-e2e-transform-asset-urls:test:e2e task failed due to port 44877 already being in use (EADDRINUSE), which is unrelated to our PR's changes to param inheritance in buildLocation. Since this project is not among the touched projects and the error has no connection to the router logic we modified, a re-run in a clean environment should resolve it.

No code changes were suggested for this issue.

Trigger a rerun:

View detailed reasoning on Nx Cloud ↗

_{🎓 Learn more about Self-Healing CI on nx.dev}