Create a custom anchor-based link while retaining router navigation.
Custom navigation UI
TanStack · Hook
useLinkProps
useLinkProps creates React anchor props from TanStack Router link options and ordinary anchor attributes. Apply the returned props to an anchor to build a navigational link.
How it works
useLinkProps converts route-link options plus ordinary anchor attributes into a props object for a native anchor. Applying the returned object to an anchor creates a link that can navigate while incorporating pathname, search parameters, hash, and location state.
Syntax
useLinkProps(options: UseLinkPropsOptions): React.AnchorHTMLAttributes<HTMLAnchorElement>Parameters
| Name | Type | Description |
|---|---|---|
options | UseLinkPropsOptions | An object combining ActiveLinkOptions with React anchor attributes; it supplies navigation details and any additional anchor props. |
Returns
A React.AnchorHTMLAttributes<HTMLAnchorElement> object that can be applied to an anchor element for navigation.
Key points
- Call the hook with one options object; its result is typed as React anchor attributes.
- Spread the returned object onto an anchor when building a custom link element.
- The resulting anchor performs TanStack Router navigation to the target location.
- Route targets may include pathname, query parameters, hash, and location state changes.
- The hook's options include the router's active-link navigation options.
- The options also support standard React anchor attributes.
- Internally, the supplied options are used to construct the link-props object returned for the anchor.
Common mistakes
- Additional anchor attributes are merged into the generated link props, so supplied values participate in the resulting object.
Example: Create a navigational anchor
import { useLinkProps } from '@tanstack/react-router'
export function ProfileLink() {
const linkProps = useLinkProps({
to: '/profile',
children: 'Profile',
className: 'profile-link',
})
return <a {...linkProps} />
}Builds anchor attributes from route options and applies them to a native anchor for client-side navigation.
When to use it
Build a component that adds project-specific anchor attributes around generated router props.
Reusable link wrappers
Navigate while encoding pathname, search, hash, or location-state changes.
Rich route targets
Interview questions
QWhat does useLinkProps return and how is it used?
It accepts an options object and returns React anchor attributes. Those attributes can be spread onto an anchor to create a link capable of navigating to a new location.
Follow-up: How does it differ from rendering Link? useLinkProps gives you the computed props, while Link is the component-level abstraction that renders the anchor.
QWhat can be passed to useLinkProps?
The options type combines ActiveLinkOptions with React.AnchorHTMLAttributes<HTMLAnchorElement>. This lets route-navigation options and normal anchor attributes be supplied together.
Follow-up: Why is that combination useful? It allows a custom anchor component to preserve native HTML attributes while using TanStack Router navigation behavior.
QWhich location parts can the generated link handle?
The generated link can represent changes to the pathname, search parameters, hash, and location state. The returned object is intended to be applied directly to an anchor element.
Follow-up: What element should consume the result? A React anchor element, because the documented return type is React.AnchorHTMLAttributes<HTMLAnchorElement>.
Related
ActiveLinkOptionsLinkLinkPropsuseNavigate