docs: document variadic path parameters

Adds the variadic section to the path-params guide and routing
concepts, includes optional and variadic parameters in the route
matching order (optional parameters were missing from it), and maps
Next.js optional catch-all segments to variadic parameters in the
migration guide.

Author: IderAghbal

docs/router/guide/path-params.md

@@ -721,6 +721,97 @@ function PostsComponent() {
 
 <!-- ::end:framework -->
 
+## Variadic Path Parameters
+
+A regular path param matches exactly one segment. A variadic path parameter, written `{...$paramName}`, matches **zero or more** segments and provides them back to you as an array. The path can keep going after it, so it also works between fixed parts of the URL:
+
+- `files/{...$path}/preview`
+- `$bucket/{...$folders}/$file`
+
+Let's build a route for files that can be nested in arbitrarily deep folders:
+
+<!-- ::start:framework -->
+
+# React
+
+```tsx title="src/routes/$bucket/{...$folders}/$file.tsx"
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/$bucket/{...$folders}/$file')({
+  loader: ({ params }) => {
+    // params.folders is an Array<string>
+    return fetchFile([params.bucket, ...params.folders, params.file])
+  },
+  component: FileComponent,
+})
+
+function FileComponent() {
+  const { bucket, folders, file } = Route.useParams()
+  return <div>{[bucket, ...folders, file].join(' / ')}</div>
+}
+```
+
+# Solid
+
+```tsx title="src/routes/$bucket/{...$folders}/$file.tsx"
+import { createFileRoute } from '@tanstack/solid-router'
+
+export const Route = createFileRoute('/$bucket/{...$folders}/$file')({
+  loader: ({ params }) => {
+    // params.folders is an Array<string>
+    return fetchFile([params.bucket, ...params.folders, params.file])
+  },
+  component: FileComponent,
+})
+
+function FileComponent() {
+  const params = Route.useParams()
+  return (
+    <div>
+      {[params().bucket, ...params().folders, params().file].join(' / ')}
+    </div>
+  )
+}
+```
+
+<!-- ::end:framework -->
+
+This one route matches `/media/kyoto.jpg`, `/media/photos/kyoto.jpg` and `/media/photos/2026/kyoto.jpg`, binding `folders` to `[]`, `['photos']` and `['photos', '2026']` respectively. The array is never `undefined` since a variadic that matched nothing gives you an empty array. Matching is non-greedy, so the variadic consumes as few segments as the rest of the path allows, and static, required or optional segments in the same position always win over it. Each matched segment is percent-decoded on its own, so an encoded `/` inside a folder name stays inside that folder's value.
+
+When navigating, pass an array for the variadic param. An empty (or omitted) array drops the segment entirely:
+
+```tsx
+function Component() {
+  return (
+    <div>
+      {/* navigates to /media/photos/2026/kyoto.jpg */}
+      <Link
+        to="/$bucket/{...$folders}/$file"
+        params={{
+          bucket: 'media',
+          folders: ['photos', '2026'],
+          file: 'kyoto.jpg',
+        }}
+      >
+        Kyoto Photo
+      </Link>
+
+      {/* navigates to /media/kyoto.jpg */}
+      <Link
+        to="/$bucket/{...$folders}/$file"
+        params={{ bucket: 'media', folders: [], file: 'kyoto.jpg' }}
+      >
+        Kyoto Photo (root)
+      </Link>
+    </div>
+  )
+}
+```
+
+A route path can contain up to three variadic segments, as long as consecutive ones are separated by at least one static segment; they resolve left to right, each consuming as little as possible. Prefixes and suffixes are not supported on variadic segments, and a variadic must be separated from a splat by at least one static segment.
+
+> 🧠 Use a variadic parameter when segments _between_ two known parts of the URL vary in depth. If you just want to capture "the rest of the URL" with no routes after it, a [splat route](../routing/routing-concepts.md#splat--catch-all-routes) (`$`) is simpler.
+
 ## Internationalization (i18n) with Optional Path Parameters
 
 Optional path parameters are excellent for implementing internationalization (i18n) routing patterns. You can use prefix patterns to handle multiple languages while maintaining clean, SEO-friendly URLs.

docs/router/routing/route-matching.md

@@ -9,6 +9,8 @@ When TanStack Router processes your route tree, all of your routes are automatic
 - Index Route
 - Static Routes (most specific to least specific)
 - Dynamic Routes (longest to shortest)
+- Optional Parameter Routes
+- Variadic Parameter Routes
 - Splat/Wildcard Routes
 
 Consider the following pseudo route tree:

docs/router/routing/routing-concepts.md

@@ -325,6 +325,58 @@ This route matches `/posts`, `/posts/tech`, and `/posts/tech/hello-world`.
 
 > 🧠 Routes with optional parameters are ranked lower in priority than exact matches, ensuring that more specific routes like `/posts/featured` are matched before `/posts/{-$category}`.
 
+## Variadic Path Parameters
+
+Variadic path parameters match **zero or more** URL segments in the middle of a path and bind them as an `Array<string>`. They use the `{...$paramName}` syntax.
+
+<!-- ::start:framework -->
+
+# React
+
+```tsx title="src/routes/files.{...$path}.preview.tsx"
+// `{...$path}` matches zero or more segments, so this route matches
+// `/files/preview`, `/files/docs/preview` and `/files/a/b/c/preview`
+import { createFileRoute } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/files/{...$path}/preview')({
+  component: PreviewComponent,
+})
+
+function PreviewComponent() {
+  const { path } = Route.useParams()
+
+  // `path` is an Array<string>: [] for `/files/preview`,
+  // ['a', 'b', 'c'] for `/files/a/b/c/preview`
+  return <div>Previewing {path.join('/') || 'the root folder'}</div>
+}
+```
+
+# Solid
+
+```tsx title="src/routes/files.{...$path}.preview.tsx"
+// `{...$path}` matches zero or more segments, so this route matches
+// `/files/preview`, `/files/docs/preview` and `/files/a/b/c/preview`
+import { createFileRoute } from '@tanstack/solid-router'
+
+export const Route = createFileRoute('/files/{...$path}/preview')({
+  component: PreviewComponent,
+})
+
+function PreviewComponent() {
+  const { path } = Route.useParams()
+
+  // `path` is an Array<string>: [] for `/files/preview`,
+  // ['a', 'b', 'c'] for `/files/a/b/c/preview`
+  return <div>Previewing {path().join('/') || 'the root folder'}</div>
+}
+```
+
+<!-- ::end:framework -->
+
+A variadic segment consumes as few segments as the rest of the pattern allows, and each matched segment is percent-decoded independently. A route path may contain up to three variadic segments as long as consecutive ones are separated by at least one static segment. Prefixes and suffixes are not supported on variadic segments. See [Path Params](../guide/path-params.md#variadic-path-parameters) for details.
+
+> 🧠 Variadic parameter routes are ranked below dynamic and optional parameter routes and above splat routes: `/docs/$section/end` and `/docs/{-$section}/end` both win over `/docs/{...$rest}/end` for `/docs/guide/end`.
+
 ## Layout Routes
 
 Layout routes are used to wrap child routes with additional components and logic. They are useful for:

docs/start/framework/react/migrate-from-next-js.md

@@ -338,14 +338,15 @@ Now that you have migrated the basic structure of your Next.js application to Ta
 
 ### Routing Concepts
 
-| Route Example                  | Next.js                            | TanStack Start            |
-| ------------------------------ | ---------------------------------- | ------------------------- |
-| Root Layout                    | `src/app/layout.tsx`               | `src/app/__root.tsx`      |
-| `/` (Home Page)                | `src/app/page.tsx`                 | `src/app/index.tsx`       |
-| `/posts` (Static Route)        | `src/app/posts/page.tsx`           | `src/app/posts.tsx`       |
-| `/posts/[slug]` (Dynamic)      | `src/app/posts/[slug]/page.tsx`    | `src/app/posts/$slug.tsx` |
-| `/posts/[...slug]` (Catch-All) | `src/app/posts/[...slug]/page.tsx` | `src/app/posts/$.tsx`     |
-| `/api/endpoint` (API Route)    | `src/app/api/endpoint/route.ts`    | `src/app/api/endpoint.ts` |
+| Route Example                             | Next.js                              | TanStack Start                 |
+| ----------------------------------------- | ------------------------------------ | ------------------------------ |
+| Root Layout                               | `src/app/layout.tsx`                 | `src/app/__root.tsx`           |
+| `/` (Home Page)                           | `src/app/page.tsx`                   | `src/app/index.tsx`            |
+| `/posts` (Static Route)                   | `src/app/posts/page.tsx`             | `src/app/posts.tsx`            |
+| `/posts/[slug]` (Dynamic)                 | `src/app/posts/[slug]/page.tsx`      | `src/app/posts/$slug.tsx`      |
+| `/posts/[...slug]` (Catch-All)            | `src/app/posts/[...slug]/page.tsx`   | `src/app/posts/$.tsx`          |
+| `/posts/[[...slug]]` (Optional Catch-All) | `src/app/posts/[[...slug]]/page.tsx` | `src/app/posts.{...$slug}.tsx` |
+| `/api/endpoint` (API Route)               | `src/app/api/endpoint/route.ts`      | `src/app/api/endpoint.ts`      |
 
 Learn more about the [Routing Concepts](/router/latest/docs/framework/react/routing/routing-concepts).