docs: Add missing mask option to documentation

[jong-kyung]

closes #6446

This PR improves the docs around route masking and navigation options, in response to #6446.
router.navigate() already supports masked navigation, but that support was not easy to find in the docs because mask was not explicitly surfaced in docs.

Changes

• Added mask to the documented ToOptions shape (via MaskOptions).
• Updated ToMaskOptions docs to clarify that it:
  • uses the same destination fields as ToOptions
  • does not allow nested mask
  • adds optional unmaskOnReload
• Updated wording in RouterOptionsType and RouterType to show the per-navigation override as mask.unmaskOnReload in NavigateOptions.
• Updated navigation.md to explicitly state:
  • ToOptions includes mask
  • NavigateOptions includes all ToOptions fields
  • LinkOptions also supports mask through NavigateOptions

Summary by CodeRabbit

• Documentation
  • Updated router documentation to clarify URL masking behavior across navigation operations.
  • Refined API documentation to provide comprehensive explanations of mask configuration options.
  • Enhanced navigation guide with detailed descriptions of masking features and unmaskOnReload behavior.
  • Improved documentation language for better clarity on how masking options work during navigation.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR updates documentation to properly expose the mask option for router navigation APIs. It introduces the ToMaskOptions type definition and extends ToOptions to include mask capability, making the existing masking functionality discoverable in the navigation guides and type references.

Changes

Cohort / File(s)	Summary
Router Configuration Docs docs/router/framework/react/api/router/RouterOptionsType.md, docs/router/framework/react/api/router/RouterType.md	Minor documentation text updates clarifying that mask.unmaskOnReload is referenced via NavigateOptions rather than a per-navigation override.
Mask Type Definition docs/router/framework/react/api/router/ToMaskOptionsType.md	Restructured type documentation from extending ToOptions to an explicit object definition with fields from, to, hash, state, and unmaskOnReload, explicitly excluding the mask property.
Navigation Options Type docs/router/framework/react/api/router/ToOptionsType.md	Added new MaskOptions type and extended ToOptions to include optional mask property of type ToMaskOptions, exposing mask capability in the public API.
Navigation Guide docs/router/framework/react/guide/navigation.md	Comprehensive documentation additions defining ToMaskOptions type and clarifying that NavigateOptions and LinkOptions support the mask option for route masking.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested labels

documentation, package: react-router

Suggested reviewers

• beaussan

Poem

🐰 A mask for the router, once hidden from sight,
Now documented clearly, shining so bright!
With NavigateOptions and LinkOptions too,
The mask option's finally in full view! ✨

🚥 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 'docs: Add missing mask option to documentation' directly and clearly describes the main change: adding documentation for the previously undocumented mask option.
Linked Issues check	✅ Passed	The PR fully addresses issue #6446 by documenting the mask option in ToOptions, NavigateOptions, and their related types with clear descriptions of mask behavior.
Out of Scope Changes check	✅ Passed	All changes are narrowly focused on documentation updates for the mask option and ToMaskOptions type, directly addressing the linked issue requirements.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit d85bf52

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

---

☁️ Nx Cloud last updated this comment at 2026-02-10 07:56:42 UTC

[pkg-pr-new]

More templates

• 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-rsc
• 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-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-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/router/@tanstack/arktype-adapter@6625

@tanstack/eslint-plugin-router

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

@tanstack/history

npm i https://pkg.pr.new/TanStack/router/@tanstack/history@6625

@tanstack/nitro-v2-vite-plugin

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-ssr-query

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

@tanstack/react-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@6625

@tanstack/react-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@6625

@tanstack/react-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@6625

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-ssr-query-core

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-router-ssr-query

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

@tanstack/solid-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@6625

@tanstack/solid-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@6625

@tanstack/solid-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@6625

@tanstack/start-client-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@6625

@tanstack/start-fn-stubs

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-fn-stubs@6625

@tanstack/start-plugin-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@6625

@tanstack/start-server-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@6625

@tanstack/start-static-server-functions

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

@tanstack/start-storage-context

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@6625

@tanstack/valibot-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@6625

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@6625

@tanstack/vue-router

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

@tanstack/vue-router-devtools

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

@tanstack/vue-router-ssr-query

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

@tanstack/vue-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start@6625

@tanstack/vue-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-client@6625

@tanstack/vue-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/vue-start-server@6625

@tanstack/zod-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@6625

commit: d85bf52

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/router/framework/react/guide/navigation.md (1)

24-69: ⚠️ Potential issue | 🟡 Minor

Type definition inconsistency: to field shown as required in guide but optional in API reference.

The inline type definitions in this guide show to: string as a required field (lines 33 and 56), but the actual type definitions in the API reference docs (ToOptionsType.md and ToMaskOptionsType.md) show to?: ValidRoutePath | string as optional. This discrepancy may confuse users about whether to is truly required.

Additionally, maintaining two versions of the ToMaskOptions definition (here and in ToMaskOptionsType.md) creates potential for drift if one is updated without the other.

Suggestions to resolve

Option 1 (Recommended): Update the guide to show to as optional to match the API reference:

 type ToOptions<
   TRouteTree extends AnyRoute = AnyRoute,
   TFrom extends RoutePaths<TRouteTree> | string = string,
   TTo extends string = '',
 > = {
   from?: string
-  to: string
+  to?: string

And similarly for ToMaskOptions:

 type ToMaskOptions<TRouteTree extends AnyRoute = AnyRoute> = {
   from?: string
-  to: string
+  to?: string

Option 2: If to is meant to be required in practice, update the API reference types to reflect this and add a comment explaining when it can be omitted.

Option 3: Add a comment in the guide explaining that to is shown as required here for typical usage but is technically optional in the type system.