Chapter 25: Custom Link

Core Idea

createLink builds a custom Link component with the same type parameters (type-safe to, params, search, etc.) as the built-in Link, letting you wrap a styled anchor, a UI library's link-like component (Chakra UI, Material-UI, Mantine, React Aria), or any other custom element while keeping full TanStack Router type safety and features like preload="intent".

Key Concepts

• createLink(Component): Wraps a base component (typically one that forwards props to an <a> or is itself link-like) and returns a component with Link's exact type parameters and prop interface.
• Motivation: Avoids repeating the same styling/behavior wrapper around Link throughout a codebase; centralizes it into one reusable, type-safe custom component.
• UI Library Integration: Documented patterns exist for wrapping React Aria Components (v1.11.0+), Chakra UI, Material-UI, and Mantine link components so their styling/behavior combines with router-aware navigation.
• Default Props Pattern: A common pattern is wrapping the createLink-produced component again to apply default props (e.g. preload={'intent'}) so all usages get preloading without repeating the prop.

Key Takeaways

1. Use createLink any time you find yourself repeating the same wrapper/styling around Link, it preserves type safety instead of losing it via a generic prop-spread wrapper.
2. createLink-based components remain compatible with router features like preload="intent", so UI-library-styled links don't have to sacrifice preloading behavior.
3. This is the standard way to integrate TanStack Router with third-party component libraries whose own link/button components need to also produce real, router-aware <a href> elements.

Connects To

• Ch 23: Navigation, defines Link's core behavior and props that createLink preserves.
• Ch 24: Link Options, a complementary reuse mechanism for navigation option objects rather than components.