Skip to content

    <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.

    app/page.tsx
    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:

    PropExampleTypeRequired
    hrefhref="/dashboard"String or ObjectYes
    replacereplace={false}Boolean-
    prefetchprefetch={false}Boolean-

    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.

    <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.

    app/page.tsx
    import Link from 'next/link';
     
    export default function Page() {
      return (
        <Link href="/dashboard" replace>
          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.

    app/page.tsx
    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:

    app/blog/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 have 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:

    middleware.js
    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>
      );
    }

    Was this helpful?