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