Improve `Link` prefetching with Tanstack Router

[kedom1337]

Is your feature request related to a problem? Please describe.
Compared to other headless UI libraries like Radix (which supports asChild), RAC does not allow rendering its components as custom components. While this design choice makes sense, it introduces limitations particularly around client-side routing and prefetching.

This issue is discussed in detail here. The TL;DR: TanStack Router performs prefetching via its own Link component, which is incompatible with RAC's Link component by default. The proposed solution is to bypass RAC’s built-in Link entirely and instead implement it manually using hooks from the react-aria library.

Describe the solution you'd like
I’d like this library to include a built-in RAC/TanStack Router-compatible Link component implemented via hooks, as described in the TanStack documentation. Ideally, this could be enabled through a setting in components.json, e.g., "framework": "tanstack".

Enabling this setting would:

• Replace the default Link component with the TanStack-compatible version
• Update other components (e.g., sidebar) to use this version accordingly

This is necessary because the TanStack-compatible Link has a different API surface and cannot be used as a drop-in replacement.

Describe alternatives you've considered
As outlined in the above linked issue, there are currently no real alternatives. RAC has made it clear that it won’t adopt an asChild-style API like Radix. The only other option is to forgo prefetching entirely which is a significant drawback, especially given that prefetching is a major selling point of using TanStack Router.

[kedom1337]

For anybody stumbling upon this same issue, here is the RAC/TanStack Router-compatible Link component that I hacked together real quick. I just pasted it from the Tanstack docs and then added the styles from the intentui Link component. Using this will still leave you without prefetching in components that use the default RAC Link like the sidebar component however.

import { createLink, type LinkComponent } from '@tanstack/react-router'
import * as React from 'react'
import type { AriaLinkOptions } from 'react-aria'
import {
  mergeProps,
  useFocusRing,
  useHover,
  useLink,
  useObjectRef,
} from 'react-aria'
import { twJoin, twMerge } from 'tailwind-merge'

interface LinkProps extends Omit<AriaLinkOptions, 'href'> {
  children?: React.ReactNode
  intent?: 'primary' | 'secondary' | 'unstyled'
  className?: string
}

const RACLinkComponent = React.forwardRef<HTMLAnchorElement, LinkProps>(
  (props, forwardedRef) => {
    const ref = useObjectRef(forwardedRef)
    const { isPressed, linkProps } = useLink(props, ref)
    const { isHovered, hoverProps } = useHover(props)
    const { isFocusVisible, isFocused, focusProps } = useFocusRing(props)

    const intent = props.intent ?? 'unstyled'

    return (
      <a
        {...mergeProps(linkProps, hoverProps, focusProps, props)}
        ref={ref}
        data-hovered={isHovered || undefined}
        data-pressed={isPressed || undefined}
        data-focus-visible={isFocusVisible || undefined}
        data-focused={isFocused || undefined}
        className={twMerge(
          props.className,
          twJoin([
            'outline-0 outline-offset-2 transition-[color,_opacity] focus-visible:outline-2 focus-visible:outline-ring forced-colors:outline-[Highlight]',
            'disabled:cursor-default disabled:opacity-60 forced-colors:disabled:text-[GrayText]',
            intent === 'unstyled' && 'text-current',
            intent === 'primary' && 'text-primary hover:underline',
            intent === 'secondary' && 'text-secondary-fg hover:underline',
          ])
        )}
      />
    )
  }
)

const CreatedLinkComponent = createLink(RACLinkComponent)
const Link: LinkComponent<typeof RACLinkComponent> = (props) => {
  return <CreatedLinkComponent {...props} />
}

export { Link }
export type { LinkProps }

[irsyadadl]

It would be nice if make a pr to the react aria components docs.

[devongovett]

FYI this is not necessary as of React Aria Components v1.11.0. You can use TanStack Router's createLink function with all React Aria Components (e.g. Link, MenuItem, etc.). See https://react-spectrum.adobe.com/react-aria/routing.html#tanstack-router

[kedom1337]

Nice that resolves this issue. It would maybe still be cool to have framework option in the CLI and do the createLink wrapping automatically

[kedom1337]

Any udpate here? I think the easiest fix would be to use the intentui Link component in all other components like the sidebar. This would allow me to just wrap createLink around the intentui Link component and be done with it. Currently the sidebar uses the Link directly from RAC which means I can't just override it in one location.

[irsyadadl]

@kedom1337 I'll make all link using link component.

[irsyadadl]

Navbar and sidebar now use link component.

#483

[kedom1337]

This now actually broke the layout for the SideBarItem when using createLink. As far as I can see the issue is that the classes for the SideBarItem are not passed down to the Link component. You should be able to reproduce this simply by wrapping the Link component with createLink right before assigning it:

const Link = createLink(
  ({ className, ref, intent = 'unstyled', ...props }: LinkProps) => {
    return (
      <LinkPrimitive
      // ...
      >
      // ...
      </LinkPrimitive>
    )
  }
)