Is RouterProvider recommended for TanStack Router, or should we use _asChild pattern instead?

[lyhoang-web-dev]

Context

We're integrating React Aria Components with TanStack Router and need guidance on the recommended approach from this link

Current Situation

Your documentation suggests using RouterProvider with module declaration:

declare module "react-aria-components" {
  interface RouterConfig {
    href: ToOptions;
    routerOptions: Omit<NavigateOptions, keyof ToOptions>;
  }
}

However, this approach loses type safety for required route params and search params.

Problem: Type Safety Loss

Example 1: Missing required params

// Route definition
"/items/$id"

// ❌ NO type error - but should fail
<MenuItem href={{ to: "/items/$id" }}>Item</MenuItem>
// Missing: params: { id: "123" }

Example 2: Missing required search params

import { createFileRoute } from "@tanstack/react-router";
import * as z from "zod/mini";
import { DevelopmentPage } from "@/pages/development";

export const Route = createFileRoute("/development")({
  component: DevelopmentPage,
  validateSearch: z.object({
    bar: z.boolean(),
  }),
});

// ❌ NO type error - but should fail
<MenuItem href={{ to: "/search", search: {} }}>Search</MenuItem>
// Missing: search: { foo: "123" }

Root Cause (research from issue below)

RouterConfig.href uses ToOptions type, which doesn't enforce validation like ValidateLinkOptions does.

Related TanStack Router issue: TanStack/router#5759

Our Workaround: _asChild Pattern

We use TanStack Router's _asChild prop (similar to createLink):

import { Link as RouterLink, ValidateLinkOptions } from "@tanstack/react-router";
import { Link as AriaLink } from "react-aria-components";

export type LinkProps<TRouter, TOptions> =
  ValidateLinkOptions<TRouter, TOptions> &  // ✅ Type-safe!
  AriaLinkProps;

export const Link = <TRouter, TOptions>(props: LinkProps<TRouter, TOptions>) => (
  <RouterLink {...props} _asChild={AriaLink} />
);

Benefits

✅ Full type safety (params & search validation)
✅ Type errors for missing required fields
✅ Consistent API with TanStack Router
✅ No need for RouterProvider

Usage

// ✅ Type-safe - works correctly
<Link to="/items/$id" params={{ id: "123" }}>Item</Link>

// ❌ Type error - missing required param
<Link to="/items/$id">Item</Link>

You can check example code in here: Stackblitz
Questions

1. Is RouterProvider still the recommended approach for TanStack Router integration despite type safety limitations?
2. Is the _asChild workaround acceptable as the primary pattern for Link, MenuItem, Breadcrumb, etc.?
3. Is there a way to make RouterProvider type-safe with TanStack Router's validation, or is this a known limitation?
4. Should the documentation be updated to mention this type safety trade-off and suggest the _asChild pattern as an alternative?

Additional Context
Version

• TanStack Router: v5.x (latest): 1.140.0
• React Aria Components version: 1.14.0
• We've successfully implemented Link, with full type safety using _asChild
• Would like to apply the same pattern to MenuItem, Breadcrumb, etc. if acceptable

Thank you for your guidance! 🙏

---

[lyhoang-web-dev]

Hi @snowystinger, sorry for annoying you.
Can you help me take a look this topic and tell me know your have fix or don't have a plan in future for this, Please tell me know. Thanks 🙏
If you don't clear or have any information, I'll response and support you.

[snowystinger]

We are discussing this a little bit right now, but I don't have any information to share yet. Tagging @devongovett as well for whenever we have something more

[devongovett]

Yes we're considering adding a render prop to allow overriding the DOM element that gets rendered by React Aria components. This would allow directly rendering a router Link component. See #9499 and feel free to leave your feedback there.