--- title: Link Component description: "Enable fast client-side navigation with the built-in `next/link` component." url: "https://nextjs.org/docs/15/app/api-reference/components/link" version: 15.5.15 lastUpdated: 2025-09-23 prerequisites: - "API Reference: /docs/15/app/api-reference" - "Components: /docs/15/app/api-reference/components" --- `` is a React component that extends the HTML `` element to provide [prefetching](/docs/app/getting-started/linking-and-navigating#prefetching) and client-side navigation between routes. It is the primary way to navigate between routes in Next.js. Basic usage: ## Reference The following props can be passed to the `` component: > **Good to know**: `` tag attributes such as `className` or `target="_blank"` can be added to `` as props and will be passed to the underlying `` element. ### `href` (required) The path or URL to navigate to. ### `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](https://developer.mozilla.org/docs/Web/API/History_API) stack. ### `scroll` **Defaults to `true`.** The default scrolling behavior of `` in Next.js **is to maintain scroll position**, similar to how browsers handle back and forwards navigation. When you navigate to a new [Page](/docs/app/api-reference/file-conventions/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. ### `prefetch` ### `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. ```tsx filename="app/page.tsx" switcher import Link from 'next/link' export default function Page() { return ( { // Only executes during SPA navigation console.log('Navigating...') // Optionally prevent navigation // e.preventDefault() }} > Dashboard ) } ``` ```jsx filename="app/page.js" switcher import Link from 'next/link' export default function Page() { return ( { // Only executes during SPA navigation console.log('Navigating...') // Optionally prevent navigation // e.preventDefault() }} > Dashboard ) } ``` > **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 `` component in different scenarios. ### Scrolling to an `id` If you'd like to scroll to a specific `id` on navigation, you can append your URL with a `#` hash link or just pass a hash link to the `href` prop. This is possible since `` renders to an `` element. ```jsx Settings // Output Settings ``` ### If the child is a custom component that wraps an `` tag ```tsx filename="components/nav-link.tsx" switcher import Link from 'next/link' import styled from 'styled-components' // This creates a custom component that wraps an tag const RedLink = styled.a` color: red; ` function NavLink({ href, name }) { return ( {name} ) } export default NavLink ``` ```jsx filename="components/nav-link.js" switcher import Link from 'next/link' import styled from 'styled-components' // This creates a custom component that wraps an tag const RedLink = styled.a` color: red; ` function NavLink({ href, name }) { return ( {name} ) } export default NavLink ``` * If you’re using [emotion](https://emotion.sh/)’s JSX pragma feature (`@jsx jsx`), you must use `passHref` even if you use an `` 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`](https://react.dev/reference/react/forwardRef): ### 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: ### Disable scrolling to the top of the page ### Prefetching links in Middleware It's common to use [Middleware](/docs/app/api-reference/file-conventions/middleware) for authentication or other purposes that involve rewriting the user to a different page. In order for the `` 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: ```ts filename="middleware.ts" switcher import { NextResponse } from 'next/server' export function middleware(request: Request) { const nextUrl = request.nextUrl if (nextUrl.pathname === '/dashboard') { if (request.cookies.authToken) { return NextResponse.rewrite(new URL('/auth/dashboard', request.url)) } else { return NextResponse.rewrite(new URL('/public/dashboard', request.url)) } } } ``` ```js filename="middleware.js" switcher import { NextResponse } from 'next/server' export function middleware(request) { const nextUrl = request.nextUrl if (nextUrl.pathname === '/dashboard') { if (request.cookies.authToken) { return NextResponse.rewrite(new URL('/auth/dashboard', request.url)) } else { return NextResponse.rewrite(new URL('/public/dashboard', request.url)) } } } ``` In this case, you would want to use the following code in your `` component: ## Version history | Version | Changes | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `v15.4.0` | Add `auto` as an alias to the default `prefetch` behavior. | | `v15.3.0` | Add `onNavigate` API | | `v13.0.0` | No longer requires a child `` tag. A [codemod](/docs/app/guides/upgrading/codemods#remove-a-tags-from-link-components) 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. | --- For an index of all available documentation, see [/docs/15/llms.txt](/docs/15/llms.txt)