fix: update state key references from 'key' to '__TSR_key'

[naoya7076]

Description

Currently, when using TanStack Router, if users define a property named key within the navigation state, its value is overridden by the router's internal logic, which assigns a random key.

For example:

https://github.com/TanStack/router/discussions/284#discussioncomment-9341612

const navigate = useNavigate();
navigate({ to: '/', state: { color: 'blue', key: 123 } });

// Defined type
declare module '@tanstack/react-router' {
  interface HistoryState {
    key?: number
    otherValue?: string
  }
}

// On navigation target
const location = useLocation();
console.log(location.state.color); // correctly "blue"
console.log(location.state.key);   // incorrectly overridden by a random string like "p7axhg"

Expected Behavior

When explicitly providing a key within the navigation state, it should preserve the user's defined value rather than being overridden by the router's internal random key.

[naoya7076]

@SeanCassiere Thank you again for your feedback. I've changed __key to __TSR_key.  If merging it for v2 is not too much trouble, I would be very happy to see it included.

[SeanCassiere]

@SeanCassiere Thank you again for your feedback. I've changed __key to __TSR_key.  If merging it for v2 is not too much trouble, I would be very happy to see it included.

@naoya7076 we currently do not have a v2 development branch open. As I mentioned earlier, I have added it onto the v2 list so that it gets done for its development.

The only path forward here, in having this merged into main at the moment, would be to have both key and __TSR_key be added in and have their functionality/values be synced during the v1 cycle. The key property would be marked as TODO: Remove in v2 using a comment. Then, when it comes time to begin working on v2, we'd go ahead and act on the TODO.

[naoya7076]

@SeanCassiere Thank you for the guidance! I've updated the implementation as requested:

• Added both key and __TSR_key properties with synced values
• Marked key with TODO: Remove in v2 comments
• Updated all affected packages and documentation

Thanks for the clear direction! 🙏

[nx-cloud[bot]]

View your CI Pipeline Execution ↗ for commit 5962a349f7cbc458f22a687888314abdcb6c53e8.

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

---

☁️ Nx Cloud last updated this comment at 2025-06-23 02:47:53 UTC

[pkg-pr-new[bot]]

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-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• 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-start-example-basic-react-query
• tanstack-start-example-basic-rsc
• tanstack-start-example-basic-static
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-example-large
• tanstack-start-example-material-ui
• 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-basic
• 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-kitchen-sink-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-solid-start-example-bare
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-static

@tanstack/arktype-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@4356

@tanstack/directive-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@4356

@tanstack/eslint-plugin-router

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

@tanstack/history

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

@tanstack/react-router

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

@tanstack/react-router-devtools

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

@tanstack/react-router-with-query

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

@tanstack/react-start

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

@tanstack/react-start-client

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

@tanstack/react-start-plugin

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

@tanstack/react-start-server

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

@tanstack/router-cli

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

@tanstack/router-core

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

@tanstack/router-devtools

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

@tanstack/router-devtools-core

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

@tanstack/router-generator

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

@tanstack/router-plugin

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

@tanstack/router-utils

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

@tanstack/router-vite-plugin

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

@tanstack/server-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@4356

@tanstack/solid-router

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

@tanstack/solid-router-devtools

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

@tanstack/solid-start

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

@tanstack/solid-start-client

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

@tanstack/solid-start-plugin

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

@tanstack/solid-start-server

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

@tanstack/start-client-core

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

@tanstack/start-plugin-core

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

@tanstack/start-server-core

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

@tanstack/start-server-functions-client

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

@tanstack/start-server-functions-fetcher

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

@tanstack/start-server-functions-server

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

@tanstack/valibot-adapter

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

@tanstack/virtual-file-routes

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

@tanstack/zod-adapter

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

commit: 5962a34

[SeanCassiere]

@naoya7076 the only thing left to resolve is the failing test.

[SeanCassiere]

I've updated the description and added the removal into the v2 checklist.

@naoya7076 thank you for taking this up and working with us on this one!