<Link>
Examples
<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.
import Link from 'next/link'
export default function Page() {
return <Link href="/dashboard">Dashboard</Link>
}
Props
Here's a summary of the props available for the Link Component:
Prop | Example | Type | Required |
---|---|---|---|
href | href="/dashboard" | String or Object | Yes |
replace | replace={false} | Boolean | - |
scroll | scroll={false} | Boolean | - |
prefetch | prefetch={false} | Boolean | - |
Good to know:
<a>
tag attributes such asclassName
ortarget="_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.
<Link href="/dashboard">Dashboard</Link>
href
can also accept an object, for example:
// Navigate to /about?name=test
<Link
href={{
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'
export default function Page() {
return (
<Link href="/dashboard" replace>
Dashboard
</Link>
)
}
scroll
Defaults to true
. The default behavior of <Link>
is to scroll to the top of a new route or to maintain the scroll position for backwards and forwards navigation. When false
, next/link
will not scroll to the top of the page after a navigation.
import Link from 'next/link'
export default function Page() {
return (
<Link href="/dashboard" scroll={false}>
Dashboard
</Link>
)
}
prefetch
Defaults to true
. When true
, next/link
will prefetch the page (denoted by the href
) in the background. This is useful for improving the performance of client-side navigations. Any <Link />
in the viewport (initially or through scroll) will be preloaded.
Prefetch can be disabled by passing prefetch={false}
. Prefetching is only enabled in production.
import Link from 'next/link'
export default function Page() {
return (
<Link href="/dashboard" prefetch={false}>
Dashboard
</Link>
)
}
Examples
Linking to Dynamic Routes
For dynamic routes, 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 app/blog/[slug]/page.js
:
import Link from 'next/link'
function Page({ posts }) {
return (
<ul>
{posts.map((post) => (
<li key={post.id}>
<Link href={`/blog/${post.slug}`}>{post.title}</Link>
</li>
))}
</ul>
)
}
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 may add something similar to the following in your Middleware to redirect the user to the correct page:
export function middleware(req) {
const nextUrl = req.nextUrl
if (nextUrl.pathname === '/dashboard') {
if (req.cookies.authToken) {
return NextResponse.rewrite(new URL('/auth/dashboard', req.url))
} else {
return NextResponse.rewrite(new URL('/public/dashboard', req.url))
}
}
}
In this case, you would want to use the following code in your <Link />
component:
import Link from 'next/link'
import useIsAuthed from './hooks/useIsAuthed'
export default function Page() {
const isAuthed = useIsAuthed()
const path = isAuthed ? '/auth/dashboard' : '/dashboard'
return (
<Link as="/dashboard" href={path}>
Dashboard
</Link>
)
}
Version History
Version | Changes |
---|---|
v13.0.0 | No longer requires a child <a> tag. A codemod is provided to automatically update your codebase. |
v10.0.0 | href props pointing to a dynamic route are automatically resolved and no longer require an as prop. |
v8.0.0 | Improved prefetching performance. |
v1.0.0 | next/link introduced. |
Was this helpful?