Link

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

Basic usage:

import Link from'next/link'exportdefaultfunctionHome() {return <Linkhref="/dashboard">Dashboard</Link>}

Reference

The following props can be passed to the <Link> component:

Good to know: <a> tag attributes such as className or target="_blank" can be added to <Link> as props and will be passed to the underlying <a> element.

href (required)

The path or URL to navigate to.

import Link from'next/link'// Navigate to /about?name=testexportdefaultfunctionHome() {return ( <Linkhref={{ pathname:'/about', query: { name:'test' }, }} > About </Link> )}

replace

Defaults to false. When true, next/link will replace the current history state instead of adding a new URL into the browser's history stack.

import Link from'next/link'exportdefaultfunctionHome() {return ( <Linkhref="/dashboard"replace> Dashboard </Link> )}

scroll

Defaults to true. The default scrolling behavior of <Link> in Next.js is to maintain scroll position, similar to how browsers handle back and forwards navigation. When you navigate to a new Page, scroll position will stay the same as long as the Page is visible in the viewport. However, if the Page is not visible in the viewport, Next.js will scroll to the top of the first Page element.

When scroll = {false}, Next.js will not attempt to scroll to the first Page element.

Good to know: Next.js checks if scroll: false before managing scroll behavior. If scrolling is enabled, it identifies the relevant DOM node for navigation and inspects each top-level element. All non-scrollable elements and those without rendered HTML are bypassed, this includes sticky or fixed positioned elements, and non-visible elements such as those calculated with getBoundingClientRect. Next.js then continues through siblings until it identifies a scrollable element that is visible in the viewport.

import Link from'next/link'exportdefaultfunctionHome() {return ( <Linkhref="/dashboard"scroll={false}> Dashboard </Link> )}

prefetch

Prefetching happens when a <Link /> component enters the user's viewport (initially or through scroll). Next.js prefetches and loads the linked route (denoted by the href) and data in the background to improve the performance of client-side navigation's. Prefetching is only enabled in production.

The following values can be passed to the prefetch prop:

• true (default): The full route and its data will be prefetched.
• false: Prefetching will not happen when entering the viewport, but will happen on hover. If you want to completely remove fetching on hover as well, consider using an <a> tag or incrementally adopting the App Router, which enables disabling prefetching on hover too.

import Link from'next/link'exportdefaultfunctionHome() {return ( <Linkhref="/dashboard"prefetch={false}> Dashboard </Link> )}

legacyBehavior

An <a> element is no longer required as a child of <Link>. Add the legacyBehavior prop to use the legacy behavior or remove the <a> to upgrade. A codemod is available to automatically upgrade your code.

Good to know: when legacyBehavior is not set to true, all anchor tag properties can be passed to next/link as well such as, className, onClick, etc.

passHref

Forces Link to send the href property to its child. Defaults to false. See the passing a functional component example for more information.

shallow

Update the path of the current page without rerunning getStaticProps, getServerSideProps or getInitialProps. Defaults to false.

import Link from'next/link'exportdefaultfunctionHome() {return ( <Linkhref="/dashboard"shallow={false}> Dashboard </Link> )}

locale

The active locale is automatically prepended. locale allows for providing a different locale. When falsehref has to include the locale as the default behavior is disabled.

import Link from'next/link'exportdefaultfunctionHome() {return ( <> {/* Default behavior: locale is prepended */} <Linkhref="/dashboard">Dashboard (with locale)</Link> {/* Disable locale prepending */} <Linkhref="/dashboard"locale={false}> Dashboard (without locale) </Link> {/* Specify a different locale */} <Linkhref="/dashboard"locale="fr"> Dashboard (French) </Link> </> )}

onNavigate

An event handler called during client-side navigation. The handler receives an event object that includes a preventDefault() method, allowing you to cancel the navigation if needed.

import Link from'next/link'exportdefaultfunctionPage() {return ( <Linkhref="/dashboard"onNavigate={(e) => {// Only executes during SPA navigationconsole.log('Navigating...')// Optionally prevent navigation// e.preventDefault() }} > Dashboard </Link> )}

Good to know: While onClick and onNavigate may seem similar, they serve different purposes. onClick executes for all click events, while onNavigate only runs during client-side navigation. Some key differences:

• When using modifier keys (Ctrl/Cmd + Click), onClick executes but onNavigate doesn't since Next.js prevents default navigation for new tabs.
• External URLs won't trigger onNavigate since it's only for client-side and same-origin navigations.
• Links with the download attribute will work with onClick but not onNavigate since the browser will treat the linked URL as a download.

Examples

The following examples demonstrate how to use the <Link> component in different scenarios.

Linking to dynamic route segments

For dynamic route segments, it can be handy to use template literals to create the link's path.

For example, you can generate a list of links to the dynamic route pages/blog/[slug].js

import Link from'next/link'functionPosts({ posts }) {return ( <ul> {posts.map((post) => ( <likey={post.id}> <Linkhref={`/blog/${post.slug}`}>{post.title}</Link> </li> ))} </ul> )}

If the child is a custom component that wraps an <a> tag

If the child of Link is a custom component that wraps an <a> tag, you must add passHref to Link. This is necessary if you’re using libraries like styled-components. Without this, the <a> tag will not have the href attribute, which hurts your site's accessibility and might affect SEO. If you're using ESLint, there is a built-in rule next/link-passhref to ensure correct usage of passHref.

import Link from'next/link'import styled from'styled-components'// This creates a custom component that wraps an <a> tagconstRedLink=styled.a` color: red;`functionNavLink({ href, name }) {return ( <Linkhref={href} passHreflegacyBehavior> <RedLink>{name}</RedLink> </Link> )}exportdefault NavLink

• If you’re using emotion’s JSX pragma feature (@jsx jsx), you must use passHref even if you use an <a> tag directly.
• The component should support onClick property to trigger navigation correctly.

Nesting a functional component

If the child of Link is a functional component, in addition to using passHref and legacyBehavior, you must wrap the component in React.forwardRef:

import Link from'next/link'import React from'react'// Define the props type for MyButtoninterfaceMyButtonProps { onClick?:React.MouseEventHandler<HTMLAnchorElement> href?:string}// Use React.ForwardRefRenderFunction to properly type the forwarded refconstMyButton:React.ForwardRefRenderFunction<HTMLAnchorElement,MyButtonProps> = ({ onClick, href }, ref) => {return ( <ahref={href} onClick={onClick} ref={ref}> Click Me </a> )}// Use React.forwardRef to wrap the componentconstForwardedMyButton=React.forwardRef(MyButton)exportdefaultfunctionHome() {return ( <Linkhref="/about"passHreflegacyBehavior> <ForwardedMyButton /> </Link> )}

Passing a URL Object

Link can also receive a URL object and it will automatically format it to create the URL string:

import Link from'next/link'functionHome() {return ( <ul> <li> <Linkhref={{ pathname:'/about', query: { name:'test' }, }} > About us </Link> </li> <li> <Linkhref={{ pathname:'/blog/[slug]', query: { slug:'my-post' }, }} > Blog Post </Link> </li> </ul> )}exportdefault Home

The above example has a link to:

• A predefined route: /about?name=test
• A dynamic route: /blog/my-post

You can use every property as defined in the Node.js URL module documentation.

Replace the URL instead of push

The default behavior of the Link component is to push a new URL into the history stack. You can use the replace prop to prevent adding a new entry, as in the following example:

import Link from'next/link'exportdefaultfunctionHome() {return ( <Linkhref="/about"replace> About us </Link> )}

Disable scrolling to the top of the page

The default behavior of Link is to scroll to the top of the page. When there is a hash defined it will scroll to the specific id, like a normal <a> tag. To prevent scrolling to the top / hash scroll={false} can be added to Link:

import Link from'next/link'exportdefaultfunctionHome() {return ( <Linkhref="/#hashid"scroll={false}> Disables scrolling to the top </Link> )}

Prefetching links in Middleware

It's common to use Middleware for authentication or other purposes that involve rewriting the user to a different page. In order for the <Link /> component to properly prefetch links with rewrites via Middleware, you need to tell Next.js both the URL to display and the URL to prefetch. This is required to avoid un-necessary fetches to middleware to know the correct route to prefetch.

For example, if you want to serve a /dashboard route that has authenticated and visitor views, you can add the following in your Middleware to redirect the user to the correct page:

import { NextResponse } from'next/server'exportfunctionmiddleware(request:Request) {constnextUrl=request.nextUrlif (nextUrl.pathname ==='/dashboard') {if (request.cookies.authToken) {returnNextResponse.rewrite(newURL('/auth/dashboard',request.url)) } else {returnNextResponse.rewrite(newURL('/public/dashboard',request.url)) } }}

In this case, you would want to use the following code in your <Link /> component:

'use client'import Link from'next/link'import useIsAuthed from'./hooks/useIsAuthed'// Your auth hookexportdefaultfunctionHome() {constisAuthed=useIsAuthed()constpath= isAuthed ?'/auth/dashboard':'/public/dashboard'return ( <Linkas="/dashboard"href={path}> Dashboard </Link> )}

Good to know: If you're using Dynamic Routes, you'll need to adapt your as and href props. For example, if you have a Dynamic Route like /dashboard/authed/[user] that you want to present differently via middleware, you would write: <Link href={{ pathname: '/dashboard/authed/[user]', query: { user: username } }} as="/dashboard/[user]">Profile</Link>.

Blocking navigation

You can use the onNavigate prop to block navigation when certain conditions are met, such as when a form has unsaved changes. When you need to block navigation across multiple components in your app (like preventing navigation from any link while a form is being edited), React Context provides a clean way to share this blocking state. First, create a context to track the navigation blocking state:

'use client'import { createContext, useState, useContext } from'react'interfaceNavigationBlockerContextType { isBlocked:booleansetIsBlocked: (isBlocked:boolean) =>void}exportconstNavigationBlockerContext=createContext<NavigationBlockerContextType>({ isBlocked:false,setIsBlocked: () => {}, })exportfunctionNavigationBlockerProvider({ children,}: { children:React.ReactNode}) {const [isBlocked,setIsBlocked] =useState(false)return ( <NavigationBlockerContext.Providervalue={{ isBlocked, setIsBlocked }}> {children} </NavigationBlockerContext.Provider> )}exportfunctionuseNavigationBlocker() {returnuseContext(NavigationBlockerContext)}

Create a form component that uses the context:

'use client'import { useNavigationBlocker } from'../contexts/navigation-blocker'exportdefaultfunctionForm() {const { setIsBlocked } =useNavigationBlocker()return ( <formonSubmit={(e) => {e.preventDefault()setIsBlocked(false) }}onChange={() =>setIsBlocked(true)} > <inputtype="text"name="name" /> <buttontype="submit">Save</button> </form> )}

Create a custom Link component that blocks navigation:

'use client'import Link from'next/link'import { useNavigationBlocker } from'../contexts/navigation-blocker'interfaceCustomLinkPropsextendsReact.ComponentProps<typeof Link> { children:React.ReactNode}exportfunctionCustomLink({ children,...props }:CustomLinkProps) {const { isBlocked } =useNavigationBlocker()return ( <LinkonNavigate={(e) => {if ( isBlocked &&!window.confirm('You have unsaved changes. Leave anyway?') ) {e.preventDefault() } }} {...props} > {children} </Link> )}

Create a navigation component:

'use client'import { CustomLink as Link } from'./custom-link'exportdefaultfunctionNav() {return ( <nav> <Linkhref="/">Home</Link> <Linkhref="/about">About</Link> </nav> )}

Finally, wrap your app with the NavigationBlockerProvider in the root layout and use the components in your page:

import { NavigationBlockerProvider } from'./contexts/navigation-blocker'exportdefaultfunctionRootLayout({ children,}: { children:React.ReactNode}) {return ( <htmllang="en"> <body> <NavigationBlockerProvider>{children}</NavigationBlockerProvider> </body> </html> )}

Then, use the Nav and Form components in your page:

import Nav from'./components/nav'import Form from'./components/form'exportdefaultfunctionPage() {return ( <div> <Nav /> <main> <h1>Welcome to the Dashboard</h1> <Form /> </main> </div> )}

When a user tries to navigate away using CustomLink while the form has unsaved changes, they'll be prompted to confirm before leaving.

Version history