<Link>

Enable fast client-side navigation with the built-in next/link component, which extends the HTML <a> element with prefetching and SPA navigation.

The <Link> component extends the HTML <a> element to provide prefetching and client-side navigation between routes. It is the primary way to navigate in Next.js.

app/page.js

import Link from 'next/link'

export default function Page() {
  return <Link href="/dashboard">Dashboard</Link>
}

Props

href · string | object · required

The path or URL to navigate to. Accepts a string or a URL object.

// String
<Link href="/dashboard">Dashboard</Link>

// URL object
<Link href={{ pathname: '/about', query: { name: 'test' } }}>
  About
</Link>

replace · boolean · default: "false"

When true, replaces the current history entry instead of pushing a new URL onto the browser history stack.

<Link href="/dashboard" replace>
  Dashboard
</Link>

scroll · boolean · default: "true"

Controls scroll behavior on navigation. When true, Next.js maintains scroll position if the page is visible in the viewport, or scrolls to the top of the first page element if not.

Set to false to disable this behavior entirely.

<Link href="/dashboard" scroll={false}>
  Dashboard
</Link>

prefetch · boolean | null · default: "null"

Controls prefetching. Prefetching only occurs in production.

• null or "auto" (default) — prefetches the full route for static routes; prefetches down to the nearest loading.js boundary for dynamic routes
• true — prefetches the full route for both static and dynamic routes
• false — disables prefetching on viewport entry and on hover

<Link href="/dashboard" prefetch={false}>
  Dashboard
</Link>

onNavigate · function

Called during client-side navigation. The event object includes preventDefault() to cancel the navigation.

<Link
  href="/dashboard"
  onNavigate={(e) => {
    console.log('Navigating...')
    // e.preventDefault() to cancel
  }}
>
  Dashboard
</Link>

onNavigate differs from onClick: it only fires during SPA navigation, not for modifier-key clicks, external URLs, or links with the download attribute.

transitionTypes · string[]

A list of transition type strings passed to React.addTransitionType during navigation. Enables <ViewTransition> components to apply animations based on the navigation type.

<Link href="/about" transitionTypes={['slide-in']}>
  About
</Link>

Standard <a> attributes such as className, target, and rel are passed through to the underlying <a> element.

Examples

Linking to dynamic segments

Use template literals to generate links to dynamic routes.

app/blog/post-list.js

import Link from 'next/link'

export default function PostList({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>{post.title}</Link>
        </li>
      ))}
    </ul>
  )
}

Active link detection

Use usePathname() to highlight the active link. Because usePathname is a client hook, extract nav links into a Client Component.

app/ui/nav-links.js

'use client'

import { usePathname } from 'next/navigation'
import Link from 'next/link'

export function Links() {
  const pathname = usePathname()

  return (
    <nav>
      <Link className={pathname === '/' ? 'active' : ''} href="/">
        Home
      </Link>
      <Link className={pathname === '/about' ? 'active' : ''} href="/about">
        About
      </Link>
    </nav>
  )
}

Scrolling to a hash

Append a # hash to the href to scroll to a specific element on the destination page.

<Link href="/dashboard#settings">Settings</Link>

Replacing instead of pushing history

<Link href="/about" replace>
  About us
</Link>

Disabling scroll to top

<Link href="/dashboard" scroll={false}>
  Dashboard
</Link>

The same option is available when using router.push():

router.push('/dashboard', { scroll: false })

Blocking navigation for unsaved changes

Use onNavigate with React Context to block navigation when a form has unsaved changes.

app/components/custom-link.js

'use client'

import Link from 'next/link'
import { useNavigationBlocker } from '../contexts/navigation-blocker'

export function CustomLink({ children, ...props }) {
  const { isBlocked } = useNavigationBlocker()

  return (
    <Link
      onNavigate={(e) => {
        if (isBlocked && !window.confirm('You have unsaved changes. Leave anyway?')) {
          e.preventDefault()
        }
      }}
      {...props}
    >
      {children}
    </Link>
  )
}

Scroll offset with sticky headers

Next.js skips fixed and sticky elements when scrolling to a target. Compensate using scroll-padding-top:

app/globals.css

html {
  scroll-padding-top: 64px; /* match your header height */
}

Version history

Version	Changes
v15.4.0	"auto" added as alias for default prefetch behavior
v15.3.0	onNavigate prop added
v13.0.0	Child <a> tag no longer required
v10.0.0	href for dynamic routes auto-resolved; as prop no longer needed
v1.0.0	next/link introduced