refactor(history): use `TSR_key` namespace in state for hash #4356

naoya7076 · 2025-06-10T13:15:39Z

Updated description by @SeanCassiere

The scope of this pull request has changed to the following:

Add __TSR_key into location.state.
__TSR_key mirrors the existing functionality of location.state.key.
Update internal functions to location.state.key to favor location.state.__TSR_key.
Update documentation to reflect location.state.__TSR_key.

Original 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:
#284 (comment)

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.

SeanCassiere

@naoya7076 thanks for opening a PR for this, but we can't ship this in within the 1.0 release-cycle since this'd be considered a breaking change.
Since we have user-facing functions (like getScrollRestorationKey) which rely on location.state.key being defined/accessible.

I'll add this to the v2 list for it to be renamed to __TSR_key.

Edit: I've added this to the v2 list.

…references

naoya7076 · 2025-06-13T05:48:12Z

@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 · 2025-06-13T06:27:48Z

@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 · 2025-06-13T13:47:08Z

@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 · 2025-06-22T23:55:39Z

View your CI Pipeline Execution ↗ for commit 5962a34.

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 · 2025-06-22T23:58:49Z

More templates

@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 · 2025-06-23T02:49:51Z

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!

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

e0ad731

github-actions bot added documentation package: react-router package: router-core package: history package: solid-router labels Jun 10, 2025

Rename 'key' in markdown and comments to __key

0245d37

SeanCassiere reviewed Jun 12, 2025

View reviewed changes

fix: rename '__key' to '__TSR_key' in ParsedHistoryState and related …

95719dc

…references

naoya7076 changed the title ~~fix: update state key references from 'key' to '__key'~~ fix: update state key references from 'key' to '__TSR_key' Jun 13, 2025

feat: support both key and __TSR_key properties

d98bd9b

naoya7076 requested a review from SeanCassiere June 17, 2025 23:55

SeanCassiere added 2 commits June 23, 2025 11:52

refactor(history): use a more descriptive variable name

121c53b

refactor(history): more similar to original impl

93b4928

SeanCassiere approved these changes Jun 22, 2025

View reviewed changes

SeanCassiere changed the title ~~fix: update state key references from 'key' to '__TSR_key'~~ refactor(history): use TSR_key namespace in state for hash Jun 22, 2025

SeanCassiere added 2 commits June 23, 2025 12:00

refactor: runtime to use __TSR_key instead of key

7369fd8

Merge branch 'main' into change-state-key

04a91db

This comment was marked as resolved.

Sign in to view

SeanCassiere added 2 commits June 23, 2025 14:23

test: resolve failing tests

8d15bf8

docs: update examples using getKey

5962a34

SeanCassiere merged commit 980159a into TanStack:main Jun 23, 2025
5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

refactor(history): use `TSR_key` namespace in state for hash #4356

refactor(history): use `TSR_key` namespace in state for hash #4356

Uh oh!

naoya7076 commented Jun 10, 2025 •

edited by SeanCassiere

Loading

Uh oh!

SeanCassiere left a comment •

edited

Loading

Uh oh!

naoya7076 commented Jun 13, 2025

Uh oh!

SeanCassiere commented Jun 13, 2025

Uh oh!

naoya7076 commented Jun 13, 2025

Uh oh!

nx-cloud bot commented Jun 22, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jun 22, 2025 •

edited

Loading

Uh oh!

This comment was marked as resolved.

Uh oh!

SeanCassiere commented Jun 23, 2025

Uh oh!

Uh oh!

Uh oh!

refactor(history): use TSR_key namespace in state for hash #4356

refactor(history): use TSR_key namespace in state for hash #4356

Uh oh!

Conversation

naoya7076 commented Jun 10, 2025 • edited by SeanCassiere Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SeanCassiere left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

naoya7076 commented Jun 13, 2025

Uh oh!

SeanCassiere commented Jun 13, 2025

Uh oh!

naoya7076 commented Jun 13, 2025

Uh oh!

nx-cloud bot commented Jun 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new bot commented Jun 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

SeanCassiere commented Jun 23, 2025

Uh oh!

Uh oh!

refactor(history): use `TSR_key` namespace in state for hash #4356

refactor(history): use `TSR_key` namespace in state for hash #4356

naoya7076 commented Jun 10, 2025 •

edited by SeanCassiere

Loading

SeanCassiere left a comment •

edited

Loading

nx-cloud bot commented Jun 22, 2025 •

edited

Loading

pkg-pr-new bot commented Jun 22, 2025 •

edited

Loading