@tanstack/react-router 1.127.9 → 1.128.0

package/dist/llms/rules/guide.js

@@ -2903,6 +2903,262 @@ const link = (
 )
 \`\`\`
 
+### Navigating with Optional Parameters
+
+Optional path parameters provide flexible navigation patterns where you can include or omit parameters as needed. Optional parameters use the \`{-$paramName}\` syntax and offer fine-grained control over URL structure.
+
+#### Parameter Inheritance vs Removal
+
+When navigating with optional parameters, you have two main strategies:
+
+**Inheriting Current Parameters**
+Use \`params: {}\` to inherit all current route parameters:
+
+\`\`\`tsx
+// Inherits current route parameters
+<Link to="/posts/{-$category}" params={{}}>
+  All Posts
+</Link>
+\`\`\`
+
+**Removing Parameters**  
+Set parameters to \`undefined\` to explicitly remove them:
+
+\`\`\`tsx
+// Removes the category parameter
+<Link to="/posts/{-$category}" params={{ category: undefined }}>
+  All Posts
+</Link>
+\`\`\`
+
+#### Basic Optional Parameter Navigation
+
+\`\`\`tsx
+// Navigate with optional parameter
+<Link
+  to="/posts/{-$category}"
+  params={{ category: 'tech' }}
+>
+  Tech Posts
+</Link>
+
+// Navigate without optional parameter
+<Link
+  to="/posts/{-$category}"
+  params={{ category: undefined }}
+>
+  All Posts
+</Link>
+
+// Navigate using parameter inheritance
+<Link
+  to="/posts/{-$category}"
+  params={{}}
+>
+  Current Category
+</Link>
+\`\`\`
+
+#### Function-Style Parameter Updates
+
+Function-style parameter updates are particularly useful with optional parameters:
+
+\`\`\`tsx
+// Remove a parameter using function syntax
+<Link
+  to="/posts/{-$category}"
+  params={(prev) => ({ ...prev, category: undefined })}
+>
+  Clear Category
+</Link>
+
+// Update a parameter while keeping others
+<Link
+  to="/articles/{-$category}/{-$slug}"
+  params={(prev) => ({ ...prev, category: 'news' })}
+>
+  News Articles
+</Link>
+
+// Conditionally set parameters
+<Link
+  to="/posts/{-$category}"
+  params={(prev) => ({
+    ...prev,
+    category: someCondition ? 'tech' : undefined
+  })}
+>
+  Conditional Category
+</Link>
+\`\`\`
+
+#### Multiple Optional Parameters
+
+When working with multiple optional parameters, you can mix and match which ones to include:
+
+\`\`\`tsx
+// Navigate with some optional parameters
+<Link
+  to="/posts/{-$category}/{-$slug}"
+  params={{ category: 'tech', slug: undefined }}
+>
+  Tech Posts
+</Link>
+
+// Remove all optional parameters
+<Link
+  to="/posts/{-$category}/{-$slug}"
+  params={{ category: undefined, slug: undefined }}
+>
+  All Posts
+</Link>
+
+// Set multiple parameters
+<Link
+  to="/posts/{-$category}/{-$slug}"
+  params={{ category: 'tech', slug: 'react-tips' }}
+>
+  Specific Post
+</Link>
+\`\`\`
+
+#### Mixed Required and Optional Parameters
+
+Optional parameters work seamlessly with required parameters:
+
+\`\`\`tsx
+// Required 'id', optional 'tab'
+<Link
+  to="/users/$id/{-$tab}"
+  params={{ id: '123', tab: 'settings' }}
+>
+  User Settings
+</Link>
+
+// Remove optional parameter while keeping required
+<Link
+  to="/users/$id/{-$tab}"
+  params={{ id: '123', tab: undefined }}
+>
+  User Profile
+</Link>
+
+// Use function style with mixed parameters
+<Link
+  to="/users/$id/{-$tab}"
+  params={(prev) => ({ ...prev, tab: 'notifications' })}
+>
+  User Notifications
+</Link>
+\`\`\`
+
+#### Advanced Optional Parameter Patterns
+
+**Prefix and Suffix Parameters**
+Optional parameters with prefix/suffix work with navigation:
+
+\`\`\`tsx
+// Navigate to file with optional name
+<Link
+  to="/files/prefix{-$name}.txt"
+  params={{ name: 'document' }}
+>
+  Document File
+</Link>
+
+// Navigate to file without optional name
+<Link
+  to="/files/prefix{-$name}.txt"
+  params={{ name: undefined }}
+>
+  Default File
+</Link>
+\`\`\`
+
+**All Optional Parameters**
+Routes where all parameters are optional:
+
+\`\`\`tsx
+// Navigate to specific date
+<Link
+  to="/{-$year}/{-$month}/{-$day}"
+  params={{ year: '2023', month: '12', day: '25' }}
+>
+  Christmas 2023
+</Link>
+
+// Navigate to partial date
+<Link
+  to="/{-$year}/{-$month}/{-$day}"
+  params={{ year: '2023', month: '12', day: undefined }}
+>
+  December 2023
+</Link>
+
+// Navigate to root with all parameters removed
+<Link
+  to="/{-$year}/{-$month}/{-$day}"
+  params={{ year: undefined, month: undefined, day: undefined }}
+>
+  Home
+</Link>
+\`\`\`
+
+#### Navigation with Search Params and Optional Parameters
+
+Optional parameters work great in combination with search params:
+
+\`\`\`tsx
+// Combine optional path params with search params
+<Link
+  to="/posts/{-$category}"
+  params={{ category: 'tech' }}
+  search={{ page: 1, sort: 'newest' }}
+>
+  Tech Posts - Page 1
+</Link>
+
+// Remove path param but keep search params
+<Link
+  to="/posts/{-$category}"
+  params={{ category: undefined }}
+  search={(prev) => prev}
+>
+  All Posts - Same Filters
+</Link>
+\`\`\`
+
+#### Imperative Navigation with Optional Parameters
+
+All the same patterns work with imperative navigation:
+
+\`\`\`tsx
+function Component() {
+  const navigate = useNavigate()
+
+  const clearFilters = () => {
+    navigate({
+      to: '/posts/{-$category}/{-$tag}',
+      params: { category: undefined, tag: undefined },
+    })
+  }
+
+  const setCategory = (category: string) => {
+    navigate({
+      to: '/posts/{-$category}/{-$tag}',
+      params: (prev) => ({ ...prev, category }),
+    })
+  }
+
+  const applyFilters = (category?: string, tag?: string) => {
+    navigate({
+      to: '/posts/{-$category}/{-$tag}',
+      params: { category, tag },
+    })
+  }
+}
+\`\`\`
+
 ### Active & Inactive Props
 
 The \`Link\` component supports two additional props: \`activeProps\` and \`inactiveProps\`. These props are functions that return additional props for the \`active\` and \`inactive\` states of the link. All props other than styles and classes passed here will override the original props passed to \`Link\`. Any styles or classes passed are merged together.
@@ -3613,6 +3869,219 @@ const router = createRouter({
 The following is the list of accepted allowed characters:
 \`;\` \`:\` \`@\` \`&\` \`=\` \`+\` \`$\` \`,\`
 
+## Optional Path Parameters
+
+Optional path parameters allow you to define route segments that may or may not be present in the URL. They use the \`{-$paramName}\` syntax and provide flexible routing patterns where certain parameters are optional.
+
+### Defining Optional Parameters
+
+Optional path parameters are defined using curly braces with a dash prefix: \`{-$paramName}\`
+
+\`\`\`tsx
+// Single optional parameter
+// src/routes/posts/{-$category}.tsx
+export const Route = createFileRoute('/posts/{-$category}')({
+  component: PostsComponent,
+})
+
+// Multiple optional parameters
+// src/routes/posts/{-$category}/{-$slug}.tsx
+export const Route = createFileRoute('/posts/{-$category}/{-$slug}')({
+  component: PostComponent,
+})
+
+// Mixed required and optional parameters
+// src/routes/users/$id/{-$tab}.tsx
+export const Route = createFileRoute('/users/$id/{-$tab}')({
+  component: UserComponent,
+})
+\`\`\`
+
+### How Optional Parameters Work
+
+Optional parameters create flexible URL patterns:
+
+- \`/posts/{-$category}\` matches both \`/posts\` and \`/posts/tech\`
+- \`/posts/{-$category}/{-$slug}\` matches \`/posts\`, \`/posts/tech\`, and \`/posts/tech/hello-world\`
+- \`/users/$id/{-$tab}\` matches \`/users/123\` and \`/users/123/settings\`
+
+When an optional parameter is not present in the URL, its value will be \`undefined\` in your route handlers and components.
+
+### Accessing Optional Parameters
+
+Optional parameters work exactly like regular parameters in your components, but their values may be \`undefined\`:
+
+\`\`\`tsx
+function PostsComponent() {
+  const { category } = Route.useParams()
+
+  return <div>{category ? \`Posts in \${category}\` : 'All Posts'}</div>
+}
+\`\`\`
+
+### Optional Parameters in Loaders
+
+Optional parameters are available in loaders and may be \`undefined\`:
+
+\`\`\`tsx
+export const Route = createFileRoute('/posts/{-$category}')({
+  loader: async ({ params }) => {
+    // params.category might be undefined
+    return fetchPosts({ category: params.category })
+  },
+})
+\`\`\`
+
+### Optional Parameters in beforeLoad
+
+Optional parameters work in \`beforeLoad\` handlers as well:
+
+\`\`\`tsx
+export const Route = createFileRoute('/posts/{-$category}')({
+  beforeLoad: async ({ params }) => {
+    if (params.category) {
+      // Validate category exists
+      await validateCategory(params.category)
+    }
+  },
+})
+\`\`\`
+
+### Advanced Optional Parameter Patterns
+
+#### With Prefix and Suffix
+
+Optional parameters support prefix and suffix patterns:
+
+\`\`\`tsx
+// File route: /files/prefix{-$name}.txt
+// Matches: /files/prefix.txt and /files/prefixdocument.txt
+export const Route = createFileRoute('/files/prefix{-$name}.txt')({
+  component: FileComponent,
+})
+
+function FileComponent() {
+  const { name } = Route.useParams()
+  return <div>File: {name || 'default'}</div>
+}
+\`\`\`
+
+#### All Optional Parameters
+
+You can create routes where all parameters are optional:
+
+\`\`\`tsx
+// Route: /{-$year}/{-$month}/{-$day}
+// Matches: /, /2023, /2023/12, /2023/12/25
+export const Route = createFileRoute('/{-$year}/{-$month}/{-$day}')({
+  component: DateComponent,
+})
+
+function DateComponent() {
+  const { year, month, day } = Route.useParams()
+
+  if (!year) return <div>Select a year</div>
+  if (!month) return <div>Year: {year}</div>
+  if (!day)
+    return (
+      <div>
+        Month: {year}/{month}
+      </div>
+    )
+
+  return (
+    <div>
+      Date: {year}/{month}/{day}
+    </div>
+  )
+}
+\`\`\`
+
+#### Optional Parameters with Wildcards
+
+Optional parameters can be combined with wildcards for complex routing patterns:
+
+\`\`\`tsx
+// Route: /docs/{-$version}/$
+// Matches: /docs/extra/path, /docs/v2/extra/path
+export const Route = createFileRoute('/docs/{-$version}/$')({
+  component: DocsComponent,
+})
+
+function DocsComponent() {
+  const { version } = Route.useParams()
+  const { _splat } = Route.useParams()
+
+  return (
+    <div>
+      Version: {version || 'latest'}
+      Path: {_splat}
+    </div>
+  )
+}
+\`\`\`
+
+### Navigating with Optional Parameters
+
+When navigating to routes with optional parameters, you have fine-grained control over which parameters to include:
+
+\`\`\`tsx
+function Navigation() {
+  return (
+    <div>
+      {/* Navigate with optional parameter */}
+      <Link to="/posts/{-$category}" params={{ category: 'tech' }}>
+        Tech Posts
+      </Link>
+
+      {/* Navigate without optional parameter */}
+      <Link to="/posts/{-$category}" params={{ category: undefined }}>
+        All Posts
+      </Link>
+
+      {/* Navigate with multiple optional parameters */}
+      <Link
+        to="/posts/{-$category}/{-$slug}"
+        params={{ category: 'tech', slug: 'react-tips' }}
+      >
+        Specific Post
+      </Link>
+    </div>
+  )
+}
+\`\`\`
+
+### Type Safety with Optional Parameters
+
+TypeScript provides full type safety for optional parameters:
+
+\`\`\`tsx
+function PostsComponent() {
+  // TypeScript knows category might be undefined
+  const { category } = Route.useParams() // category: string | undefined
+
+  // Safe navigation
+  const categoryUpper = category?.toUpperCase()
+
+  return <div>{categoryUpper || 'All Categories'}</div>
+}
+
+// Navigation is type-safe and flexible
+<Link
+  to="/posts/{-$category}"
+  params={{ category: 'tech' }} // ✅ Valid - string
+>
+  Tech Posts
+</Link>
+
+<Link
+  to="/posts/{-$category}"
+  params={{ category: 123 }} // ✅ Valid - number (auto-stringified)
+>
+  Category 123
+</Link>
+\`\`\`
+
 # Preloading
 
 Preloading in TanStack Router is a way to load a route before the user actually navigates to it. This is useful for routes that are likely to be visited by the user next. For example, if you have a list of posts and the user is likely to click on one of them, you can preload the post route so that it's ready to go when the user clicks on it.