Link and Navigation API Reference

Purpose and Scope

This reference covers the Router APIs that describe user-initiated navigation, render-time navigation, reusable navigation option objects, and route-match-based rendering. In TanStack Router, a navigation can update the pathname, search params, hash, and location state, so these APIs are not limited to traditional anchor links. The main public surfaces on this page are the Link component, the Navigate component, the linkOptions helper, the LinkOptions, LinkProps, and NavigateOptions types, and the MatchRoute component for conditional rendering based on route matching.

Sources: docs/router/api/router/linkComponent.md, docs/router/api/router/navigateComponent.md, docs/router/api/router/linkOptions.md, docs/router/api/router/matchRouteComponent.md

Use this page when you need to decide which navigation primitive fits a particular interaction. Link is the normal declarative anchor-style API for clickable navigation. Navigate is a component that navigates when it successfully renders, which is useful for render-driven redirects inside component trees. linkOptions is a type-checking helper for extracting a reusable object literal that can later be spread into Link, passed to a navigation call, or used with redirect-oriented flows. MatchRoute is not itself a navigation trigger; it is a rendering helper that answers whether a route target matches the current or pending route state.

Sources: docs/router/api/router/linkComponent.md, docs/router/api/router/navigateComponent.md, docs/router/api/router/linkOptions.md, docs/router/api/router/matchRouteComponent.md

Relevant Source Files

• docs/router/api/router/linkComponent.md documents the Link component, its prop type, return value, examples, and path-param encoding behavior.
• docs/router/api/router/navigateComponent.md documents the Navigate component, its render-triggered effect behavior, accepted options, and null return value.
• docs/router/api/router/linkOptions.md documents the linkOptions helper and shows how to create reusable, strongly typed link option objects.
• docs/router/api/router/LinkOptionsType.md defines LinkOptions as NavigateOptions plus anchor- and link-specific behavior such as target, active matching, preloading, preload delay, and disabling.
• docs/router/api/router/LinkPropsType.md defines LinkProps as active link options plus anchor attributes, with a special children shape that can react to active state.
• docs/router/api/router/NavigateOptionsType.md defines the shared navigation controls for history replacement, scroll reset, hash scrolling, view transitions, blockers, document reloads, and raw href navigation.
• docs/router/api/router/matchRouteComponent.md documents MatchRoute, its relationship to useMatchRoute, its children contract, and its route-match example.

API Components

Link is the primary component for rendering an anchor element that navigates within a Router application. It accepts LinkProps together with a React ref to an HTMLAnchorElement, and it returns an anchor element that can move the app to a new location. Its options can describe a route target, typed params, a search updater, hash changes, and state changes. The documented example uses to="/somewhere/$somewhereId", supplies params={{ somewhereId: 'baz' }}, and derives the next search object from the previous search state.

Sources: docs/router/api/router/linkComponent.md, docs/router/api/router/LinkPropsType.md

Navigate is the component form of imperative navigation. Instead of rendering an anchor, it returns null and performs navigation from inside a useEffect hook after it has rendered successfully. That behavior matters because it makes Navigate appropriate for component-tree decisions rather than click handling. For example, a route component can render Navigate after it determines that a user should be sent elsewhere, while still using the same NavigateOptions shape that describes normal Router navigation actions.

Sources: docs/router/api/router/navigateComponent.md, docs/router/api/router/NavigateOptionsType.md

linkOptions exists to preserve exact type inference when navigation configuration is factored out of JSX. It type-checks an object literal intended for Link, navigate, or redirect, and returns an object literal with the exact type inferred from the input. This is useful when a design system component, menu definition, dashboard tile, or redirect helper wants to define a canonical target once and reuse it without losing route, search, and params checking at the call site.

Sources: docs/router/api/router/linkOptions.md

MatchRoute is the component equivalent of useMatchRoute. It accepts the same route-matching options as that hook and adds a children API for conditional rendering. The child may be a normal React node rendered only when the route matches, or a function that receives either the matched params or false. The function form is especially useful for persistent UI, such as a spinner, navigation badge, or panel, that should always render but change its props when a target route is pending or active.

Sources: docs/router/api/router/matchRouteComponent.md

Compact Reference

The core type layering is important. NavigateOptions is the shared base for describing where and how a navigation should happen. LinkOptions extends that base with anchor-specific and link-specific behavior, including target, activeOptions, preload, preloadDelay, and disabled. LinkProps then combines active link options with standard React anchor attributes, while replacing the usual children shape with either a React node or a function that receives { isActive: boolean }. This layering lets one route target participate in multiple UI patterns while still preserving Router-specific type checking.

Sources: docs/router/api/router/LinkOptionsType.md, docs/router/api/router/LinkPropsType.md, docs/router/api/router/NavigateOptionsType.md

Navigation Options

NavigateOptions extends ToOptions, so it inherits the target-location description used by Router navigation. The additional options control how the transition is committed and what browser behaviors accompany it. replace defaults to false; when true, the router commits the next location with history replacement instead of a history push. resetScroll defaults to true, resetting scroll to the top after the location is committed. hashScrollIntoView also defaults to true, and it may be set to false or to a ScrollIntoViewOptions object when hash scrolling needs finer control.

Sources: docs/router/api/router/NavigateOptionsType.md

The same options also cover newer or more forceful navigation behaviors. viewTransition defaults to false, but can be true or a ViewTransitionOptions object so route navigations can use document.startViewTransition when the browser supports it. ignoreBlocker defaults to false and allows a navigation to bypass blockers when set to true. reloadDocument defaults to false; when true, navigation to a route inside the router triggers a full page load instead of single-page-app navigation. Finally, href can be used instead of to when the caller already has a fully built href, such as an external target.

Sources: docs/router/api/router/NavigateOptionsType.md

LinkOptions adds behavior that only makes sense for rendered links. target is the normal anchor target attribute. activeOptions configures how the router determines whether the link is active. preload can be disabled or set to strategies documented as intent, viewport, or render, with preloadDelay delaying intent preloading and canceling it if the intent ends before the delay. disabled changes rendering by omitting the href attribute, which is different from merely styling a link as unavailable because the browser no longer sees it as a navigable anchor.

Sources: docs/router/api/router/LinkOptionsType.md

Usage Patterns and Examples

A typical Link usage supplies a typed route target and the params required by that route. Search params may be supplied directly or as an updater that receives previous search state. This keeps navigation code close to the UI while still letting the router validate the shape of route params and search state through its generated route types. Because Link renders an anchor element, standard anchor attributes can be combined with Router options, and children can be a function when the label or styling needs to respond to active state.

Sources: docs/router/api/router/linkComponent.md, docs/router/api/router/LinkPropsType.md

import { Link } from '@tanstack/react-router'
 
function Component() {
  return (
    <Link
      to="/somewhere/$somewhereId"
      params={{ somewhereId: 'baz' }}
      search={(prev) => ({ ...prev, foo: 'bar' })}
    >
      Click me
    </Link>
  )
}

Path params are URL encoded by default. The documented example shows a username param containing @ becoming %40foo in the path. If an application intentionally wants selected characters to remain unencoded in path params, the router can be configured with pathParamsAllowedCharacters. That setting belongs on router creation rather than on an individual Link, so it should be treated as a routing policy decision for the application instead of a one-off escape hatch for a single navigation.

Sources: docs/router/api/router/linkComponent.md

import { createRouter } from '@tanstack/react-router'
 
const router = createRouter({
  routeTree,
  pathParamsAllowedCharacters: ['@'],
})

Reusable navigation options are a good fit for linkOptions when the same destination appears in multiple places. The documented example creates userLinkOptions for a dashboard users route with nested search state, then spreads it into Link. The important detail is not just reuse; it is that the object literal is checked at definition time and retains the exact inferred type. That helps prevent drift between menu definitions, redirect code, and rendered links as routes evolve.

Sources: docs/router/api/router/linkOptions.md

const userLinkOptions = linkOptions({
  to: '/dashboard/users/user',
  search: {
    usersView: {
      sortBy: 'email',
      filterBy: 'filter',
    },
    userId: 0,
  },
})
 
function DashboardComponent() {
  return <Link {...userLinkOptions} />
}

Route Matching and Conditional Rendering

MatchRoute should be read as a rendering companion to navigation, not as a navigation command. It evaluates match options and renders according to whether the target route matches. Its children prop can be a React node, which is rendered if the route is matched, or a function that receives matched params or false. That makes it useful for pending indicators, route-aware navigation chrome, contextual controls, and components that need route params only when a route is active or pending.

Sources: docs/router/api/router/matchRouteComponent.md

import { MatchRoute } from '@tanstack/react-router'
 
function Component() {
  return (
    <div>
      <MatchRoute to="/posts/$postId" params={{ postId: '123' }} pending>
        {(match) => <Spinner show={!!match} wait="delay-50" />}
      </MatchRoute>
    </div>
  )
}

A useful mental model is to separate target description, navigation execution, and match observation. NavigateOptions and LinkOptions describe destinations and behavior. Link executes navigation through an anchor interaction. Navigate executes navigation as a render side effect. linkOptions preserves reusable target descriptions. MatchRoute observes whether a target matches so UI can respond. Keeping those roles separate makes navigation code easier to audit, because redirects, links, preloads, active states, and pending indicators each have a distinct API surface.

Sources: docs/router/api/router/LinkOptionsType.md, docs/router/api/router/NavigateOptionsType.md, docs/router/api/router/linkComponent.md, docs/router/api/router/navigateComponent.md, docs/router/api/router/linkOptions.md, docs/router/api/router/matchRouteComponent.md

Next Steps

For day-to-day application code, start with Link for visible navigation and extract shared destinations with linkOptions only when reuse or design-system boundaries make it worthwhile. Use Navigate when rendering a component should cause a navigation, and use MatchRoute when the UI needs to reflect active or pending route state without navigating. If a navigation involves scroll behavior, blockers, view transitions, document reloads, or a raw href, review the NavigateOptions fields before choosing defaults.

Related pages: navigation-and-links, custom-links-and-link-options, router-hooks-api-reference, errors-redirects-search-api-reference