Remove legacyBehavior from Link component on Next.js 15

[fuma-nama]

Goals

Next.js 15 as a major release, it's a good time to remove the legacy behavior from Next.js Link component.
It was added in Next.js 13, after two major releases, I think it makes sense to remove it.

This can:

• Reduce the effort to maintain the component
• Reduce the confusion for developers when they saw these props which are no longer documented in the App Router docs.

Non-Goals

Add new features

Background

When playing with Next.js 15 canary, I found some props like as are no longer documented while they are kept in the implementation.

I was surprised by the complexity of the implementation of the Next.js Link component, some legacy functionalities should be removed.

Proposal

• Remove legacyBehavior prop
• Remove as prop
• Remove passHref prop

I'm willing to provide a PR

[shshaw]

I am curious about the future of <Link> and passHref/legacyBehavior. If I have a component that renders an anchor element in a stylized way or with certain functionality that needs to work with or without Link, what would be the recommended way to do that without passHref and legacyBehavior?

[fuma-nama]

These props are not required to use Link, they have been deprecated, and I could not see examples that they will be required.

They were kept to ensure backward compatibility as it was a breaking change, Link had an entirely different usage before, and the new usage supports all functionality that the previous one provides.

Next.js Link is now a component that renders HTML <a> element, the docs no longer mention deprecated usage.

[shshaw]

Next.js Link is now a component that renders HTML <a> element, the docs no longer mention deprecated usage.

What do you mean? Even the Next 15 docs still reference passHref and legacyBehavior in the examples. https://nextjs.org/docs/canary/app/api-reference/components/link#if-the-child-is-a-custom-component-that-wraps-an-a-tag

If they are deprecated, those need to be removed.

Regardless: What is the proper usage of <Link> for custom components that render <a>, assuming that passHref and legacyBehavior are not available? Some clear examples of that should be provided in the documentation if the expectation is the other approaches will no longer be available.

[shshaw]

If you're unsure what I'm referring to, here's a quick example.

// Component that renders an anchor. It cannot render a <Link> directly because it might be used in contexts outside of Next.
function MyFancyLink(props) {
  return <a {...props} styles={/* or CSS modules, or Tailwind, or whatever. Maybe even some custom functionality or animation. */} />;
}

// How can this work without `passHref`? Will the output be `<a href="/signup"><a styles={...}>Sign up now!</a></a>`?
<Link href="/signup">
  <MyFancyLink>Sign up now!</MyFancyLink>
</Link>

[fuma-nama]

That's a good point.

If the link component is from another library that doesn't use the Next.js Link component, you can likely replace it with Link component (not using the original link).
If it's for styled components, this should work:

const StyledLink = styled(Link)`
  color: #BF4F74;
  font-weight: bold;
`;

Also see: https://nextjs.org/docs/pages/api-reference/components/link#legacybehavior

I think the name legacyBehavior and not listed on the reference section (see the linked docs) makes it weird to use the API. I would prefer either removing the need of legacyBehavior, or simply remove all these APIs and provide other solutions (e.g. passing onClick like the current Link component).

[menewman]

+1 to @shshaw's point. I found this thread while researching best practices/guidelines for using link components from libraries that aren't Next-specific. In that case, it seems like the only real way to handle it is using passHref + legacyBehavior -- so if the latter were removed, it would be great to have another way to solve the same use case.

I do agree that it feels weird/unreliable to have to use a prop with legacy in the name.

[lukenofurther]

We have an external library providing styled components. That library does not, and likely never will, use NextJS, so incorporating a NextJS Link into the component we use for links (just for our use case) isn't going to happen. Simply using the NextJS Link instead of the link component from the external library means we lose all the styling that the rest of the app uses, and we'd have to add all the styles (along with dynamic theming) to it separately somehow, which wouldn't be trivial.

[lukenofurther]

It would be good to replace the legacy workaround with a well-designed replacement functionality for the same use case: allow the use of a custom non-NextJS component that already renders out an a element, has custom styling and/or functionality attached to it that's vital to it functioning correctly in the app, and is black-boxed so can't be modified.

How about adding a Component prop (or similar, e.g. as) to Link that any custom a-rendering component could be passed into? If passed, Link would extend it instead of rendering out its own a element. Something like:

import { ExternalLink } from 'external-library'
import Link from 'next/link'

const MyLink = ({ children, href }) => {
  return (
    <Link as={ExternalLink} href={href}>
      {children}
    </Link>
  )
}

[Netail]

That is, if the external library is willing to support the as-prop. The external library could be managed by a community or external org

[nielsvdpol]

Maybe a quick solve would be to deprecate legacyBehavior and use passHref for the functionality as discussed above?

Also found more next 15 documentation where legacyBehavior is used: https://nextjs.org/docs/messages/link-passhref

[nlwillia]

I found this discussion while researching a warning in dev mode of my 15.3 pages router app.

The latest API reference for pages router still references legacyBehavior and passHref with no mention of deprecation. Ugly as these are, I don't see an answer for what to do when using 3rd party styled anchor components.

`legacyBehavior` is deprecated and will be removed in a future release. A codemod is available to upgrade your components:

npx @next/codemod@latest new-link .

Learn more: https://nextjs.org/docs/app/building-your-application/upgrading/codemods#remove-a-tags-from-link-components

[MubashirullahD]

Same. And I find this such a waste of my time. The docs doesn't say what I should do now. What am I supposed to do with code like this:

"use client";

import { useState } from "react";
import Link from "next/link";
import { Menu } from "lucide-react";
import { Button } from "@/components/ui/button";
import {
  Sheet,
  SheetContent,
  SheetTrigger,
  SheetHeader,
  SheetTitle,
  SheetClose,
  SheetDescription,
} from "@/components/ui/sheet";
import {
  NavigationMenu,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
} from "@/components/ui/navigation-menu";
import { cn } from "@/lib/utils";

const mainLinks = [
  {
    title: "Documentation",
    href: `${process.env.NEXT_PUBLIC_DOCS_URL}`,
  },
  {
    title: "Queryloop Labs",
    href: "/querylooplabs",
  },
  {
    title: "Pricing",
    href: "/pricing",
  },
  {
    title: "Blog",
    href: "/blog",
  },
];

export function NavigationLinks() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <div className="hidden md:flex flex-1 justify-between items-center">
        {/* Centered Navigation Menu */}
        <div className="flex-1 flex justify-center">
          <NavigationMenu>
            <NavigationMenuList className="space-x-2">
              {mainLinks.map((link) => (
                <NavigationMenuItem key={link.title}>
                  <Link href={link.href} legacyBehavior passHref>
                    <NavigationMenuLink
                      className={cn(
                        "group inline-flex h-9 items-center justify-center rounded-md px-4 py-2",
                        "text-sm font-medium transition-colors",
                        "text-brand-silver hover:text-white hover:bg-white/[0.03]",
                        "focus:bg-accent focus:text-accent-foreground focus:outline-none",
                        "disabled:pointer-events-none disabled:opacity-50"
                      )}
                    >
                      {link.title}
                    </NavigationMenuLink>
                  </Link>
                </NavigationMenuItem>
              ))}
            </NavigationMenuList>
          </NavigationMenu>
        </div>

        {/* Auth Buttons - Adjusted spacing and hover states */}
        <div className="flex items-center gap-3">
          <Link href={`${process.env.NEXT_PUBLIC_APP_URL}/auth/login`}>
            <Button
              variant="ghost"
              size="sm"
              className="text-brand-silver hover:text-white hover:bg-white/[0.03]"
            >
              Login
            </Button>
          </Link>
          <Link href={`${process.env.NEXT_PUBLIC_APP_URL}/auth/signup`}>
            <Button
              size="sm"
              className="bg-primary-brand hover:bg-primary-brand/90 text-white px-6"
            >
              Sign up for free
            </Button>
          </Link>
        </div>
      </div>

      {/* Mobile menu with improved styling and auto-close on link click */}
      <Sheet open={open} onOpenChange={setOpen}>
        <SheetTrigger asChild className="md:hidden">
          <Button
            variant="ghost"
            size="icon"
            className="text-brand-silver hover:text-white hover:bg-white/[0.03]"
          >
            <Menu className="!w-[25px] !h-[25px]" />
          </Button>
        </SheetTrigger>
        <SheetContent
          side="right"
          className="w-[300px] bg-brand-nav border-brand-nav p-6"
        >
          <SheetHeader>
            <SheetTitle className="text-brand-silver">Menu</SheetTitle>
            <SheetDescription className="text-brand-silver/60"></SheetDescription>
          </SheetHeader>
          <nav className="flex flex-col mt-8" aria-label="Mobile">
            {mainLinks.map((link) => (
              <SheetClose asChild key={link.title}>
                <Link
                  href={link.href}
                  className="py-3 text-base font-medium text-brand-silver hover:text-white transition-colors"
                  onClick={() => setOpen(false)}
                >
                  {link.title}
                </Link>
              </SheetClose>
            ))}
            <div className="flex flex-col gap-3 mt-8">
              <SheetClose asChild>
                <Link href={`${process.env.NEXT_PUBLIC_APP_URL}/auth/login`}>
                  <Button
                    variant="ghost"
                    className="w-full text-brand-silver hover:text-white hover:bg-white/[0.03]"
                  >
                    Login
                  </Button>
                </Link>
              </SheetClose>
              <SheetClose asChild>
                <Link href={`${process.env.NEXT_PUBLIC_APP_URL}/auth/signup`}>
                  <Button className="w-full bg-primary-brand hover:bg-primary-brand/90 text-white">
                    Sign up for free
                  </Button>
                </Link>
              </SheetClose>
            </div>
          </nav>
        </SheetContent>
      </Sheet>
    </>
  );
}

If I remove legacy behaviour, it will give me this warning:

In HTML, <a> cannot be a descendant of <a>.
This will cause a hydration error.

[benjick]

Same issue in app router. What's the migration path?

<Link href="/foobar" legacyBehavior passHref>
  <NavigationMenuLink>
    foobar
  </NavigationMenuLink>
</Link>

[benjick]

shadcn-ui/ui#7266

[Coderamrin]

so i found the the solution here:
you have to put the link inside navigationmenulink and set it aschild:

<NavigationMenuItem>
          <NavigationMenuLink asChild className={navigationMenuTriggerStyle()}>
            <Link href="/docs">Documentation</Link>
          </NavigationMenuLink>
 </NavigationMenuItem>

this fixed the issue for me.

[snps-mrojas]

What about a link that needs to be injected with custom properties(ie data-*)? How can that be achieved without using children components for Link?

[snps-mrojas]

If these are removed, what would be the proper way to inject custom attributes to a Link? Like dataset attributes for example(data-*).

[hrmcdonald]

We maintain a web component design system library. We cannot forward a Next.js <Link> component into the internals of the certain web components that receive href (and all other relevant <a> attributes) to forward them to the correct anchor element within the web component.

The legacyBehavior allows us to expose wrapped components for our Next.js users by forwarding the right attributes to the web component just fine. There is no good alternative if that is deprecated. What would the recommendation be for this kind of use case where <Link> still won't work?

EDIT: I'll note that this suggestion above would allow us to still handle this nicely for even this use case.

[stubinubin]

If you wanted to have a clickable table row with Link in a table then legacy behavior is needed.

[alexbrazier]

We have the same issue using material-ui components, and there doesn't seem to be an easy way to fix this if the legacyBehavior prop is removed. The suggestion to add a component prop would probably work for us. Here is an example of how we use it:

import NextLink from 'next/link';
import { Button } from '@mui/material';

const ButtonLink = ({ href, ...props }) => (
  <NextLink href={href} passHref legacyBehavior>
    <Button {...props} />
  </NextLink>
);

Semantically, we can achieve the same thing by just doing <Button href={href} {...props} /> but then we don't get any of the next/link features.

Without the legacyBehavior prop we end up with <a href="..."><button>...</button></a> rather than <a href="..." style="buttonStyles">...</a>

A solution to this would be great, either by keeping/renaming the prop or adding a new component prop.

[blynx]

Not sure if I'm late to the party, just scrambled this together.
Would be interested in your solution if you had one meanwhile.

import NextLink, { type LinkProps } from "next/link";

export const nextLinkWith = (linkProps: LinkProps) => {
  return ({ children, ...props }) => {
    let mergedProps = { ...props, ...linkProps };
    return (
      <NextLink {...mergedProps}>
        {children}
      </NextLink>
    );
  }
}

// usage
<ListItemButton component={nextLinkWith({ href: "/path", shallow: true })}>...</ListItemButton>

Cheers!

[emmgfx]

@blynx I've wrote an article with one solution, but I don't want to do spam here, it's appropriate if I share the link?

[blynx]

@emmgfx Well, i just sneaked my way through and found your article, feel free to share it. :)

Interesting, your polymorphism solution is kinda the "opposite way" to my approach. But I wonder how you'd integrate with Material UI components? I feel like it's not possible, but maybe I miss something? (Is it still a requirement on your side?)

Oh, you're not the author of the original post, sorry. ^^
Still, I don't think I can use that approach directly with Material UI components. I might miss something though.

Thank you for your reply also!

[emmgfx]

@blynx Im the author of one article, but I don't know what article did you read 😂

Maybe the wrapper solution from the MUI docs works for you? Uses the polymorphism with a wrapper for the Link component.

https://mui.com/material-ui/integrations/nextjs/#next-js-v16-client-component-restriction

[blynx]

I'm sure I read your article, followed your profile link ;)

Oh damn, thanks! Didn't consider looking into the mui docs regarding that problem. They also seem to apply the excessive props to the provided component. I could use that directly.

[icyJoseph]

Let's track this other discussion: #76329 (comment)