fix(router-core): allow retained search params to reset to defaults

[schiller-manuel]

fixes#7558

Summary by CodeRabbit

• Bug Fixes

  • Fixed an issue where retained search params could incorrectly override navigations that explicitly specify default-valued search parameters when using stripSearchParams.

• Tests

  • Added test cases to verify search parameter retention behavior with search param stripping.

[coderabbitai]

Ready to act? Review this PR in Change Stack to turn feedback into patch suggestions you can inspect and refine.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4af3c113-b878-46ea-ab67-fcfd0b057f86

📥 Commits

Reviewing files that changed from the base of the PR and between e99e855 and 869fab1.

📒 Files selected for processing (6)

• .changeset/fix-retain-strip-explicit-defaults.md
• packages/router-core/src/route.ts
• packages/router-core/src/router.ts
• packages/router-core/src/searchMiddleware.ts
• packages/router-core/src/utils.ts
• packages/router-core/tests/build-location.test.ts

---

📝 Walkthrough

Walkthrough

Router search middleware now tracks explicitly-provided navigation search input via a new meta.explicit field, allowing retainSearchParams and stripSearchParams to properly handle scenarios where a user explicitly navigates to default-valued parameters that would otherwise be stripped.

Changes

Search explicit tracking and retain/strip behavior

Layer / File(s)	Summary
Search metadata contract and explicit tracking infrastructure packages/router-core/src/route.ts, packages/router-core/src/utils.ts, packages/router-core/src/router.ts	SearchMiddlewareMeta adds an optional explicit field. hasOwn is exported from utils. Router middleware stores the computed explicit search value into meta.explicit during functional updates.
Retain/strip behavior with explicit-default awareness and validation packages/router-core/src/searchMiddleware.ts, packages/router-core/tests/build-location.test.ts, .changeset/fix-retain-strip-explicit-defaults.md	retainSearchParams imports hasOwn and refactors removal/retention logic across three key branches to consult meta.explicit alongside meta.removed and meta.removedAny, preventing retained params from blocking explicit navigation to defaults. Two new test cases verify the fix for both keyed and whole-retention modes, and a changeset documents the patch-level fix.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• TanStack/router#7555: Both PRs modify packages/router-core/src/searchMiddleware.ts to prevent retainSearchParams from reintroducing search keys that stripSearchParams should remove, using explicit metadata to coordinate the two functions.
• TanStack/router#7557: Both PRs add regression test cases to packages/router-core/tests/build-location.test.ts for retainSearchParams behavior under search param changes.
• TanStack/router#7549: Both PRs modify packages/router-core/src/searchMiddleware.ts and router metadata plumbing to fix retainSearchParams handling of default values, though using different metadata mechanisms.

Suggested reviewers

• chorobin

Poem

🐰 A rabbit hops through search param seas,
Where strips and retains dance with ease—
Explicit defaults now shine so clear,
No more lost params, the fix is here!
Defaults restored, the path is bright. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main fix: allowing retained search params to reset to default values, which directly addresses the linked issue #7558.
Linked Issues check	✅ Passed	The PR implements the required fix for issue #7558 by tracking explicit search param values and using them in retainSearchParams to allow params to reset to defaults when used with stripSearchParams.
Out of Scope Changes check	✅ Passed	All code changes are directly related to fixing the retainSearchParams and stripSearchParams interaction issue; no unrelated modifications are present.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-7558

---

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit b073a1d

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	10m 28s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	2m 12s	View ↗

💡 Verify your cache is correct by running tasks in a sandbox. Read docs ↗

---

☁️ Nx Cloud last updated this comment at 2026-06-06 08:25:30 UTC

[github-actions]

🚀 Changeset Version Preview

1 package(s) bumped directly, 22 bumped as dependents.

🟩 Patch bumps

Package	Version	Reason
@tanstack/router-core	1.171.11 → 1.171.12	Changeset
@tanstack/react-router	1.170.13 → 1.170.14	Dependent
@tanstack/react-start	1.168.22 → 1.168.23	Dependent
@tanstack/react-start-client	1.168.10 → 1.168.11	Dependent
@tanstack/react-start-rsc	0.1.21 → 0.1.22	Dependent
@tanstack/react-start-server	1.167.16 → 1.167.17	Dependent
@tanstack/router-cli	1.167.15 → 1.167.16	Dependent
@tanstack/router-generator	1.167.15 → 1.167.16	Dependent
@tanstack/router-plugin	1.168.16 → 1.168.17	Dependent
@tanstack/router-vite-plugin	1.167.16 → 1.167.17	Dependent
@tanstack/solid-router	1.170.13 → 1.170.14	Dependent
@tanstack/solid-start	1.168.22 → 1.168.23	Dependent
@tanstack/solid-start-client	1.168.10 → 1.168.11	Dependent
@tanstack/solid-start-server	1.167.16 → 1.167.17	Dependent
@tanstack/start-client-core	1.170.9 → 1.170.10	Dependent
@tanstack/start-plugin-core	1.171.14 → 1.171.15	Dependent
@tanstack/start-server-core	1.169.11 → 1.169.12	Dependent
@tanstack/start-static-server-functions	1.167.14 → 1.167.15	Dependent
@tanstack/start-storage-context	1.167.13 → 1.167.14	Dependent
@tanstack/vue-router	1.170.13 → 1.170.14	Dependent
@tanstack/vue-start	1.168.21 → 1.168.22	Dependent
@tanstack/vue-start-client	1.167.14 → 1.167.15	Dependent
@tanstack/vue-start-server	1.167.16 → 1.167.17	Dependent

[github-actions]

Bundle Size Benchmarks

• Commit: 5943d950ffd7
• Measured at: 2026-06-06T08:15:52.278Z
• Baseline source: history:e99e855258e3
• Dashboard: bundle-size history

Scenario	Current (gzip)	Delta vs baseline	Initial gzip	Raw	Brotli	Trend
react-router.minimal	87.26 KiB	+18 B (+0.02%)	87.12 KiB	273.77 KiB	75.89 KiB	▇▁▁▁▁▁▁▁▆▆▆█
react-router.full	91.09 KiB	+71 B (+0.08%)	90.95 KiB	286.16 KiB	79.16 KiB	▂▁▁▁▁▁▁▁▇▇▇█
solid-router.minimal	35.48 KiB	+16 B (+0.04%)	35.36 KiB	106.07 KiB	31.97 KiB	▇▁▁▁▁▁▁▁▆▆▆█
solid-router.full	40.55 KiB	+42 B (+0.10%)	40.42 KiB	121.29 KiB	36.43 KiB	▂▁▁▁▁▁▁▁▇▇▇█
vue-router.minimal	52.97 KiB	+24 B (+0.04%)	52.84 KiB	150.09 KiB	47.65 KiB	█▁▁▁▁▁▁▁▅▅▅█
vue-router.full	58.96 KiB	+31 B (+0.05%)	58.83 KiB	168.84 KiB	52.81 KiB	▂▁▁▁▁▁▁▁▇▇▇█
react-start.minimal	101.88 KiB	+19 B (+0.02%)	101.74 KiB	322.09 KiB	88.14 KiB	█▁▁▁▁▁▁▁▆▆▆█
react-start.deferred-hydration	102.62 KiB	+17 B (+0.02%)	101.76 KiB	323.46 KiB	88.90 KiB	▇▁▁▁▁▁▁▁▆▆▆█
react-start.full	105.29 KiB	+43 B (+0.04%)	105.15 KiB	332.40 KiB	90.98 KiB	▅▁▁▁▁▁▁▁▄▄▄█
react-start.rsbuild.minimal	99.59 KiB	+21 B (+0.02%)	99.42 KiB	316.58 KiB	85.76 KiB	▇▁▁▁▁▁▁▁▅▅▅█
react-start.rsbuild.minimal-iife	99.99 KiB	+20 B (+0.02%)	99.82 KiB	317.51 KiB	86.04 KiB	▇▁▁▁▁▁▁▁▅▅▅█
react-start.rsbuild.full	102.85 KiB	+20 B (+0.02%)	102.68 KiB	326.97 KiB	88.40 KiB	█▁▁▁▁▁▁▁▅▅▅█
solid-start.minimal	49.60 KiB	+21 B (+0.04%)	49.46 KiB	152.14 KiB	43.77 KiB	▆▁▁▁▁▁▁▁▅▅▅█
solid-start.deferred-hydration	52.86 KiB	+20 B (+0.04%)	49.52 KiB	160.18 KiB	46.76 KiB	▆▁▁▁▁▁▁▁▅▅▅█
solid-start.full	55.38 KiB	+19 B (+0.03%)	55.25 KiB	169.07 KiB	48.83 KiB	▇▁▁▁▁▁▁▁▅▅▅█
vue-start.minimal	71.02 KiB	+23 B (+0.03%)	70.89 KiB	207.23 KiB	62.85 KiB	▇▁▁▁▁▁▁▁▅▅▅█
vue-start.full	74.98 KiB	+22 B (+0.03%)	74.85 KiB	219.75 KiB	66.30 KiB	▇▁▁▁▁▁▁▁▅▅▅█

Current gzip tracks all emitted client JS chunks. Initial gzip tracks only the entry/import graph. Trend sparkline is historical current gzip ending with this PR measurement; lower is better.

[pkg-pr-new]

More templates

• 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-router-vue-example-basic-jsx
• tanstack-router-vue-example-basic-file-based-jsx
• tanstack-router-vue-example-basic-file-based-sfc
• 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/arktype-adapter

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

@tanstack/eslint-plugin-router

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

@tanstack/eslint-plugin-start

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

@tanstack/history

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

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-rsc

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-fn-stubs

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

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

@tanstack/vue-start-client

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

@tanstack/vue-start-server

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

@tanstack/zod-adapter

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

commit: 869fab1

[codspeed-hq]

Merging this PR will not alter performance

✅ 4 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing fix-7558 (869fab1) with main (e99e855)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩