expose TRouter generic in custom link wrappers?

[lyhoang-web-dev]

Background

We're building a design system on top of TanStack Router. Our BaseLink component wraps RouterLink with React
Aria's Link for accessibility (focus management, keyboard
navigation, aria-disabled, etc.).

We deliberately avoided createLink() because it introduces extra component nesting (our component already has
multiple internal layers), and we noticed that createLink() internally uses _asChild anyway — so we use it
directly:

// src/shared/ui/base-link/base-link.tsx
import {
  type RegisteredRouter,
  Link as RouterLink,
  type ValidateLinkOptions,
} from "@tanstack/react-router";
import { Link as AriaLink, type LinkProps as AriaLinkProps } from "react-aria-components";

export type BaseLinkProps<TOptions = unknown> = Omit<
  AriaLinkProps,
  "className" | "style" | "children"
> &
  ValidateLinkOptions<RegisteredRouter, TOptions> & {
    // React Aria handles disabled state — map it so TSR doesn't preload disabled links
    disabled?: never;
  };

export const BaseLink = <TOptions,>(props: BaseLinkProps<TOptions>): ReactNode => {
  return (
    <RouterLink
      {...props}
      disabled={!!props.isDisabled}
      _asChild={AriaLink}
    />
  );
};

A styled consumer wraps it:

// src/shared/ui/link/link.tsx
export const Link = <TOptions,>(props: BaseLinkProps<TOptions>): ReactNode => {
  const { className, ...rest } = props;
  return (
    <BaseLink
      className={clsx(css.link, className)}
      {...(rest as BaseLinkProps<TOptions>)}
    />
  );
};

---

Question 1 — Should TRouter be exposed?

TanStack Router's own Link component exposes TRouter with a default:

// From @tanstack/react-router type definitions
export type LinkComponent<TComp, TDefaultFrom extends string = string> = <
  TRouter extends AnyRouter = RegisteredRouter, // 👈 exposed with default
  const TFrom extends string = TDefaultFrom,
  const TTo extends string | undefined = undefined,
  // ...
>(props: LinkComponentProps<TComp, TRouter, TFrom, TTo, ...>) => ReactElement;

Our current implementation hardcodes RegisteredRouter in ValidateLinkOptions<RegisteredRouter, TOptions>.

The proposed change would mirror TanStack's own pattern:

import {
  type AnyRouter,
  type RegisteredRouter,
  Link as RouterLink,
  type ValidateLinkOptions,
} from "@tanstack/react-router";

export type BaseLinkProps<
  TRouter extends AnyRouter = RegisteredRouter, // 👈 expose with default
  TOptions = unknown,
> = Omit<AriaLinkProps, "className" | "style" | "children"> &
  ValidateLinkOptions<TRouter, TOptions> & {
    disabled?: never;
  };

export const BaseLink = <
  TRouter extends AnyRouter = RegisteredRouter,
  TOptions = unknown,
>(
  props: BaseLinkProps<TRouter, TOptions>,
): ReactNode => {
  return (
    <RouterLink
      {...props}
      disabled={!!props.isDisabled}
      _asChild={AriaLink}
    />
  );
};

Our assumption: Exposing TRouter lets consumers pass a non-globally-registered router, which is useful for:

• Storybook stories (memory/mock router)
• Unit tests (isolated router instances)
• Library code that ships independently of a specific app router

The question: Is this the recommended pattern for application-level custom link components, or is hardcoding
RegisteredRouter acceptable/preferred?

---

Question 2 — Is _asChild a stable/intentional public API?

We rely on the _asChild prop to swap the rendered element:

<RouterLink _asChild={AriaLink} />

We noticed this is how createLink() works internally, but _asChild does not appear in the public documentation.
Our concern:

• Could this be removed or renamed in a future minor/patch release without a breaking change notice?
• Is there a documented, stable alternative that achieves the same result (render a custom component) without the
  extra nesting that createLink() introduces?

We added a comment in our code acknowledging this risk:

// We could use TanStack's `createLink()` function with a custom `BaseLink` component,
// but this increases the component tree depth and more code, so we do the same thing
// as the `createLink()` function does internally. If TSR ever removes this property,
// we can switch to `createLink()` instead.
_asChild={AriaLink}

Is this a safe long-term approach, or should we use createLink() despite the nesting overhead?

---

Versions

Package	Version
@tanstack/react-router	1.16.x
react-aria-components	1.16.0
Framework	React + Vite

[travisbreaks]

createLink already gives you the TRouter generic for free. When you do createLink(YourComponent), the returned component inherits the full TRouter, TFrom, TTo signature. Consumers get autocomplete on to, params, search, etc. at every call site without any extra work from the component author.

For your React Aria case:

import { createLink, type LinkComponent } from '@tanstack/react-router'
import { Link as AriaLink } from 'react-aria-components'

const BaseLinkInner = React.forwardRef<HTMLAnchorElement, React.ComponentPropsWithoutRef<typeof AriaLink> & { disabled?: boolean }>(
  (props, ref) => <AriaLink {...props} ref={ref} isDisabled={props.disabled} />
)

export const BaseLink: LinkComponent<typeof BaseLinkInner> = createLink(BaseLinkInner)

On _asChild: it's an internal implementation detail that powers createLink. Use createLink instead; same zero-nesting rendering, same prop forwarding, but it's the documented API path. If the internals change, createLink keeps working.

For Storybook/testing, wrapping stories in a RouterProvider with a memory router is usually simpler than parameterizing TRouter at the component level. The generic is there if you need it though.

One friction point to watch with React Aria: TSR's preload-on-intent behavior works through createLink but not through RAC's RouterProvider integration. Same for data-status="active" and activeProps/inactiveProps. If you need those, the createLink wrapper is the right path.

[tamish-max]

My bias here would be:

• if the component is app-local, RegisteredRouter is perfectly fine
• if it’s a reusable design-system package, don’t bake the app router into the package API

For the reusable case, createLink() is still the safest route because it preserves the full router generics (TRouter, TFrom, TTo, params/search inference) without depending on internal props like _asChild.

A nice compromise is to keep the styling/accessibility primitive router-agnostic, then create the typed router binding in the app layer:

export const AppLink = createLink(BaseLinkInner)

That way:

• the DS stays portable
• the app gets full TanStack Router inference
• you avoid coupling to _asChild, which feels more internal than public API surface

So I probably wouldn’t ask for exposing TRouter on the DS component itself unless that package is intentionally app-specific.