feat(router): Add useHistoryState hook for type-safe state management

docs/router/framework/react/api/router/useHistoryStateHook.md

@@ -0,0 +1,152 @@
+---
+id: useHistoryStateHook
+title: useHistoryState hook
+---
+
+The `useHistoryState` hook returns the state object that was passed during navigation to the closest match or a specific route match.
+
+## useHistoryState options
+
+The `useHistoryState` hook accepts an optional `options` object.
+
+### `opts.from` option
+
+- Type: `string`
+- Optional
+- The route ID to get state from. If not provided, the state from the closest match will be used.
+
+### `opts.strict` option
+
+- Type: `boolean`
+- Optional - `default: true`
+- If `true`, the state object type will be strictly typed based on the route's `validateState`.
+- If `false`, the hook returns a loosely typed `Partial<Record<string, unknown>>` object.
+
+### `opts.shouldThrow` option
+
+- Type: `boolean`
+- Optional
+- `default: true`
+- If `false`, `useHistoryState` will not throw an invariant exception in case a match was not found in the currently rendered matches; in this case, it will return `undefined`.
+
+### `opts.select` option
+
+- Optional
+- `(state: StateType) => TSelected`
+- If supplied, this function will be called with the state object and the return value will be returned from `useHistoryState`. This value will also be used to determine if the hook should re-render its parent component using shallow equality checks.
+
+### `opts.structuralSharing` option
+
+- Type: `boolean`
+- Optional
+- Configures whether structural sharing is enabled for the value returned by `select`.
+- See the [Render Optimizations guide](../../guide/render-optimizations.md) for more information.
+
+## useHistoryState returns
+
+- The state object passed during navigation to the specified route, or `TSelected` if a `select` function is provided.
+- Returns `undefined` if no match is found and `shouldThrow` is `false`.
+
+## State Validation
+
+You can validate the state object by defining a `validateState` function on your route:
+
+```tsx
+const route = createRoute({
+  // ...
+  validateState: (input) =>
+    z
+      .object({
+        color: z.enum(['white', 'red', 'green']).catch('white'),
+        key: z.string().catch(''),
+      })
+      .parse(input),
+})
+```
+
+This ensures type safety and validation for your route's state.
+
+## Examples
+
+```tsx
+import { useHistoryState } from '@tanstack/react-router'
+
+// Get route API for a specific route
+const routeApi = getRouteApi('/posts/$postId')
+
+function Component() {
+  // Get state from the closest match
+  const state = useHistoryState()
+
+  // OR
+
+  // Get state from a specific route
+  const routeState = useHistoryState({ from: '/posts/$postId' })
+
+  // OR
+
+  // Use the route API
+  const apiState = routeApi.useHistoryState()
+
+  // OR
+
+  // Select a specific property from the state
+  const color = useHistoryState({
+    from: '/posts/$postId',
+    select: (state) => state.color,
+  })
+
+  // OR
+
+  // Get state without throwing an error if the match is not found
+  const optionalState = useHistoryState({ shouldThrow: false })
+
+  // ...
+}
+```
+
+### Complete Example
+
+```tsx
+// Define a route with state validation
+const postRoute = createRoute({
+  getParentRoute: () => postsLayoutRoute,
+  path: 'post',
+  validateState: (input) =>
+    z
+      .object({
+        color: z.enum(['white', 'red', 'green']).catch('white'),
+        key: z.string().catch(''),
+      })
+      .parse(input),
+  component: PostComponent,
+})
+
+// Navigate with state
+function PostsLayoutComponent() {
+  return (
+    <Link
+      to={postRoute.to}
+      state={{
+        color: 'red',
+        key: 'test-value',
+      }}
+    >
+      View Post
+    </Link>
+  )
+}
+
+// Use the state in a component
+function PostComponent() {
+  const post = postRoute.useLoaderData()
+  const { color } = postRoute.useHistoryState()
+
+  return (
+    <div className="space-y-2">
+      <h4 className="text-xl font-bold">{post.title}</h4>
+      <h4 style={{ color }}>Colored by state</h4>
+    </div>
+  )
+}
+```

examples/react/basic-history-state/.gitignore

@@ -0,0 +1,10 @@
+node_modules
+.DS_Store
+dist
+dist-ssr
+*.local
+
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/

examples/react/basic-history-state/.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+  "files.watcherExclude": {
+    "**/routeTree.gen.ts": true
+  },
+  "search.exclude": {
+    "**/routeTree.gen.ts": true
+  },
+  "files.readonlyInclude": {
+    "**/routeTree.gen.ts": true
+  }
+}

examples/react/basic-history-state/README.md

@@ -0,0 +1,6 @@
+# Example
+
+To run this example:
+
+- `npm install` or `yarn`
+- `npm start` or `yarn start`

examples/react/basic-history-state/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

examples/react/basic-history-state/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "tanstack-router-react-example-basic-history-state",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port=3000",
+    "build": "vite build && tsc --noEmit",
+    "serve": "vite preview",
+    "start": "vite"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "^4.1.18",
+    "@tanstack/react-router": "^1.158.4",
+    "@tanstack/react-router-devtools": "^1.158.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "redaxios": "^0.5.1",
+    "tailwindcss": "^4.1.18",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react": "^4.3.4",
+    "typescript": "^5.7.2",
+    "vite": "^7.3.1"
+  }
+}

examples/react/basic-history-state/src/main.tsx

@@ -0,0 +1,146 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import {
+  Link,
+  Outlet,
+  RouterProvider,
+  createRootRoute,
+  createRoute,
+  createRouter,
+} from '@tanstack/react-router'
+import { TanStackRouterDevtools } from '@tanstack/react-router-devtools'
+import { z } from 'zod'
+import './styles.css'
+
+const rootRoute = createRootRoute({
+  component: RootComponent,
+  notFoundComponent: () => {
+    return <p>This is the notFoundComponent configured on root route</p>
+  },
+})
+
+function RootComponent() {
+  return (
+    <div className="bg-gradient-to-r from-green-700 to-lime-600 text-white">
+      <div className="p-2 flex gap-2 text-lg bg-black/40 shadow-xl">
+        <Link
+          to="/"
+          activeProps={{
+            className: 'font-bold',
+          }}
+          activeOptions={{ exact: true }}
+        >
+          Home
+        </Link>
+        <Link
+          to="/state-examples"
+          activeProps={{
+            className: 'font-bold',
+          }}
+        >
+          State Examples
+        </Link>
+      </div>
+      <Outlet />
+      <TanStackRouterDevtools position="bottom-right" />
+    </div>
+  )
+}
+const indexRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/',
+  component: IndexComponent,
+})
+
+function IndexComponent() {
+  return (
+    <div className="p-2">
+      <h3>Welcome Home!</h3>
+    </div>
+  )
+}
+
+// Route to demonstrate various useHistoryState usages
+const stateExamplesRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: 'state-examples',
+  component: StateExamplesComponent,
+})
+
+const stateDestinationRoute = createRoute({
+  getParentRoute: () => stateExamplesRoute,
+  path: 'destination',
+  validateState: (input: {
+    example: string
+    count: number
+    options: Array<string>
+  }) =>
+    z
+      .object({
+        example: z.string(),
+        count: z.number(),
+        options: z.array(z.string()),
+      })
+      .parse(input),
+  component: StateDestinationComponent,
+})
+
+function StateExamplesComponent() {
+  return (
+    <div className="p-2">
+      <h3 className="text-xl font-bold mb-4">useHistoryState Examples</h3>
+      <div className="flex gap-4">
+        <Link
+          to={stateDestinationRoute.to}
+          state={{
+            example: 'Test Data',
+            count: 42,
+            options: ['Option 1', 'Option 2', 'Option 3'],
+          }}
+          className="bg-green-600 px-3 py-2 rounded hover:bg-green-500"
+        >
+          Link with State
+        </Link>
+      </div>
+      <Outlet />
+    </div>
+  )
+}
+
+function StateDestinationComponent() {
+  const state = stateDestinationRoute.useHistoryState()
+  return (
+    <div className="mt-4 p-4 bg-black/20 rounded">
+      <h4 className="text-lg font-bold mb-2">State Data Display</h4>
+      <pre className="whitespace-pre-wrap bg-black/30 p-2 rounded text-sm mt-2">
+        {JSON.stringify(state, null, 2)}
+      </pre>
+    </div>
+  )
+}
+
+const routeTree = rootRoute.addChildren([
+  stateExamplesRoute.addChildren([stateDestinationRoute]),
+  indexRoute,
+])
+
+const router = createRouter({
+  routeTree,
+  defaultPreload: 'intent',
+  defaultStaleTime: 5000,
+  scrollRestoration: true,
+})
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router
+  }
+}
+
+const rootElement = document.getElementById('app')!
+
+if (!rootElement.innerHTML) {
+  const root = ReactDOM.createRoot(rootElement)
+
+  root.render(<RouterProvider router={router} />)
+}

examples/react/basic-history-state/src/styles.css

@@ -0,0 +1,21 @@
+@import 'tailwindcss' source('../');
+
+@layer base {
+  *,
+  ::after,
+  ::before,
+  ::backdrop,
+  ::file-selector-button {
+    border-color: var(--color-gray-200, currentcolor);
+  }
+}
+
+html {
+  color-scheme: light dark;
+}
+* {
+  @apply border-gray-200 dark:border-gray-800;
+}
+body {
+  @apply bg-gray-50 text-gray-950 dark:bg-gray-900 dark:text-gray-200;
+}