Skip to main content
A progressively enhanced <a href> wrapper to enable navigation with client-side routing. 
import { Link } from "react-router";

<Link to="/dashboard">Dashboard</Link>

​
Type Declaration

export interface LinkProps
  extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
  discover?: DiscoverBehavior;
  prefetch?: PrefetchBehavior;
  reloadDocument?: boolean;
  replace?: boolean;
  state?: any;
  preventScrollReset?: boolean;
  relative?: RelativeRoutingType;
  to: To;
  viewTransition?: boolean;
  unstable_defaultShouldRevalidate?: boolean;
  unstable_mask?: To;
}

export const Link: React.ForwardRefExoticComponent<
  LinkProps & React.RefAttributes<HTMLAnchorElement>
>;

type To = string | Partial<Path>;
type DiscoverBehavior = "render" | "none";
type PrefetchBehavior = "none" | "intent" | "render" | "viewport";
type RelativeRoutingType = "route" | "path";

​
Props

​
to
To
required
Can be a string or a partial Path object:
<Link to="/dashboard" />

<Link
  to={{
    pathname: "/dashboard",
    search: "?sort=name",
    hash: "#section",
  }}
/>
​
replace
boolean
Replaces the current entry in the History stack instead of pushing a new one.
<Link to="/dashboard" replace />

# with a history stack like this
A -> B

# normal link click pushes a new entry
A -> B -> C

# but with `replace`, B is replaced by C
A -> C
​
state
any
Adds persistent client side routing state to the next location.
<Link to="/profile" state={{ from: "dashboard" }} />
The location state is accessed from the location:
function Profile() {
  const location = useLocation();
  console.log(location.state); // { from: "dashboard" }
}
​
preventScrollReset
boolean
Prevents the scroll position from being reset to the top of the window when the link is clicked and the app is using ScrollRestoration.
<Link to="?tab=one" preventScrollReset />
​
relative
RelativeRoutingType
Defines the relative path behavior for the link.
<Link to=".." /> {/* default: "route" */}
<Link to=".." relative="route" />
<Link to=".." relative="path" />
  • route (default) - Resolves relative to the route pattern
  • path - Resolves relative to the URL path
​
reloadDocument
boolean
Will use document navigation instead of client side routing when the link is clicked.
<Link to="/logout" reloadDocument />
​
viewTransition
boolean
Enables a View Transition for this navigation.
<Link to="/profile" viewTransition>
  View Profile
</Link>
To apply specific styles for the transition, see useViewTransitionState.
​
prefetch
PrefetchBehavior
Defines the data and module prefetching behavior for the link.
<Link to="/dashboard" prefetch="intent" />
  • none (default) - No prefetching
  • intent - Prefetches when the user hovers or focuses the link
  • render - Prefetches when the link renders
  • viewport - Prefetches when the link is in the viewport (useful for mobile)
​
discover
DiscoverBehavior
Defines the link lazy route discovery behavior.
<Link to="/admin" discover="none" />
  • render (default) - Discover the route when the link renders
  • none - Don’t eagerly discover, only discover if the link is clicked
​
unstable_mask
To
Masked path for this navigation. Navigates to one location but displays a different URL in the browser.
<Link
  to="/gallery?image=1"
  unstable_mask="/images/1"
>
  <img src="image-1.jpg" />
</Link>

​
Examples

​
Basic Navigation

import { Link } from "react-router";

function Nav() {
  return (
    <nav>
      <Link to="/">Home</Link>
      <Link to="/about">About</Link>
      <Link to="/contact">Contact</Link>
    </nav>
  );
}

​
With Search Params

<Link to={{ pathname: "/search", search: "?q=react+router" }}>
  Search for React Router
</Link>

// or
<Link to="/search?q=react+router">
  Search for React Router
</Link>

function UserList({ users }) {
  return (
    <ul>
      {users.map((user) => (
        <li key={user.id}>
          <Link to={`/users/${user.id}`}>{user.name}</Link>
        </li>
      ))}
    </ul>
  );
}

​
With State

<Link
  to="/edit"
  state={{ from: location.pathname }}
>
  Edit
</Link>

function EditPage() {
  const location = useLocation();
  const from = location.state?.from || "/";

  return (
    <div>
      <button onClick={() => navigate(from)}>Cancel</button>
    </div>
  );
}

​
Replace History

<Link to="/new-page" replace>
  Replace Current Page
</Link>

​
Prefetching

<Link to="/dashboard" prefetch="intent">
  Dashboard (prefetch on hover)
</Link>

<Link to="/profile" prefetch="render">
  Profile (prefetch on render)
</Link>

​
All HTML Attributes

Since Link renders an <a> element, all standard anchor attributes are supported: 
<Link
  to="/docs"
  className="nav-link"
  style={{ color: "blue" }}
  target="_blank"
  rel="noopener noreferrer"
>
  Documentation
</Link>

​
Notes

  • Relative links are resolved relative to the route hierarchy by default
  • External URLs are detected automatically and render as standard <a> tags
  • Supports all standard <a> HTML attributes
  • Progressive enhancement: works with JavaScript disabled if using proper forms

Build docs developers (and LLMs) love

Get started for freeTalk to us