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