docs: skipRouteOnParseError docs WIP

docs/router/config.json

@@ -237,6 +237,10 @@
               "label": "Path Params",
               "to": "framework/react/guide/path-params"
             },
+            {
+              "label": "Validating Path Params",
+              "to": "framework/react/guide/validating-path-params"
+            },
             {
               "label": "Search Params",
               "to": "framework/react/guide/search-params"
@@ -354,6 +358,10 @@
               "label": "Path Params",
               "to": "framework/solid/guide/path-params"
             },
+            {
+              "label": "Validating Path Params",
+              "to": "framework/solid/guide/validating-path-params"
+            },
             {
               "label": "Search Params",
               "to": "framework/solid/guide/search-params"

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

@@ -88,6 +88,27 @@ The `RouteOptions` type accepts an object with the following properties:
 - Type: `(params: TParams) => Record<string, string>`
 - A function that will be called when this route's parsed params are being used to build a location. This function should return a valid object of `Record<string, string>` mapping.
 
+### `skipRouteOnParseError` property (⚠️ experimental)
+
+> [!WARNING]
+> The `skipRouteOnParseError` option is currently **experimental** and may change in future releases.
+
+- Type:
+
+```tsx
+type skipRouteOnParseError = {
+  params?: boolean
+  priority?: number
+}
+```
+
+- Optional
+- By default, when a route's `params.parse` function throws an error, the route will match and then show an error state during render. With `skipRouteOnParseError.params` enabled, the router will skip routes whose `params.parse` function throws and continue searching for alternative matching routes.
+- See [Guides > Path Params > Validating path parameters during matching](../../guide/path-params#validating-path-parameters-during-matching) for detailed usage examples.
+
+> [!IMPORTANT]
+> **Performance impact**: This option has a **non-negligible performance cost** and should only be enabled when needed. Routes with `skipRouteOnParseError` are placed on separate branches in the route matching tree instead of sharing nodes with other dynamic routes. This reduces the tree's ability to efficiently narrow down matches and requires testing more routes, even for routes that wouldn't match the path structure alone.
+
 ### `beforeLoad` method
 
 - Type:

docs/router/framework/react/guide/path-params.md

@@ -738,6 +738,18 @@ function ShopComponent() {
 
 Optional path parameters provide a powerful and flexible foundation for implementing internationalization in your TanStack Router applications. Whether you prefer prefix-based or combined approaches, you can create clean, SEO-friendly URLs while maintaining excellent developer experience and type safety.
 
+## Validating and Transforming Path Parameters
+
+Path parameters are captured from URLs as strings, but you often need to transform them to other types (numbers, dates) or validate they meet specific criteria (UUIDs, patterns). TanStack Router provides `params.parse` and `params.stringify` options for this purpose.
+
+For a comprehensive guide on validating and transforming path parameters, including:
+
+- Using `params.parse` to transform and validate parameters
+- Understanding error handling with `errorComponent`
+- Using the experimental `skipRouteOnParseError` feature for type-specific routes
+
+See the dedicated [Validating Path Params](./validating-path-params.md) guide.
+
 ## Allowed Characters
 
 By default, path params are escaped with `encodeURIComponent`. If you want to allow other valid URI characters (e.g. `@` or `+`), you can specify that in your [RouterOptions](../api/router/RouterOptionsType.md#pathparamsallowedcharacters-property).