next.js: Link API breaks a11y intuition

Feature request

I want a more intuitive Link API which respects expectations we have around native a tags.

Is your feature request related to a problem? Please describe.

The current link API looks like the following:

<Link href="/about">
  <a>here</a>
</Link>

This is problematic for a few reasons:

  1. It breaks intuition around a11y. When I see an a tag without an href, alarm bells go off, because that is a UX anti-pattern. In fact, this API makes it impossible to appease the anchor-is-valid eslint-plugin-jsx-a11y rule (see https://github.com/evcohen/eslint-plugin-jsx-a11y/issues/402).
  2. It requires a call to cloneElement which should be avoided as its behavior is confusing. (How would I know my a tag will be given an href? Nothing about this API suggests that.)

Describe the solution you’d like

I would like a solution which doesn’t require you to type an a tag without an href and also doesn’t require you to duplicate the href information.

Describe alternatives you’ve considered

There are a few good alternatives:

  1. Default to a tag if no children are given:
<Link href="/about" />

This is the approach react-router uses and it works quite well.


  1. Use a render prop:
<Link href="/about">
  {href => <a href={href}>here</a>}
</Link>

This method appeases the anchor-is-valid rule and doesn’t require the user to duplicate href information since the build href is passed down to the component they are rendering.


  1. Component injection:
<Link href="/about" component={a} />

A combination of 1 and 2 would be powerful enough to cover all reasonable use cases.

Additional context

https://github.com/zeit/next.js/commit/6431f5fce2593d8cadb81841eb0e717facbe4aa6

About this issue

  • Original URL
  • State: closed
  • Created 8 years ago
  • Reactions: 246
  • Comments: 22 (5 by maintainers)

Commits related to this issue

Most upvoted comments

I think this is really important. Right now, Next.js is competing with Gatsby and I’ve realized very quickly that I cannot use Next.js due to the lack of accessibility support. Accessibility is highly important and should be a priority (and goes further than just complying with jsx-a11y).

This issue from 2018 is still relevant. All three solutions proposed in the original post are great. They’re called out as breaking changes but I would point out that the current api could continue to be supported, making it a non-breaking change. Simply adding any of those 3 options would make Next.js play nicely with jsx-a11y.

Still an issue in 2021

We’re still working on solving this. It’s more complicated than you’re making it out to be as you’re not considering the hundreds of thousands existing Next.js applications that would not be able to upgrade to a version that has the proposed solution in this issue.

In Next.js 10 we introduced https://nextjs.org/blog/next-10#automatic-resolving-of-href as an incremental step towards this. And there’s an open RFC to build on top of that: https://github.com/vercel/next.js/discussions/8207 to enable <Link to=""> to automatically handle the <a> always being injected. Using href for this behavior would cause issues when people upgrade, potentially a codemod could be written though.

https://twitter.com/timneutkens/status/1295363065056301056

Hitting this with an old school bump.

Still an issue in 2021, and taking off the a11y guardrails linting is not an option for big teams and projects.

Hi guys, any news on how to handle this properly?

An alternative (but hacky) solution is to enable the passHref property and set the inner href to a dummy value. Next.js will override the dummy value with the correct value from the outer component, so everything will work correctly and it’ll pass the jsx-a11y/anchor-is-valid rule.

  <Link href="/my-amazing-page" passHref>
    <a href="dummy">Go to my amazing page</a>
  </Link>

Worth pointing out that the above solution (https://github.com/evcohen/eslint-plugin-jsx-a11y/issues/402#issuecomment-368305051) disables the rule’s check for an href attribute altogether. That’s 90% of the linting rule’s value for me.

Any progress on this? running into the same issue trying to setup tests for a11y things.

@timneutkens Would you accept a PR that would uses a similar approach like this? It would be a pretty big breaking change but imo it’s worth it. I think the current next/link API i one of next’s weak points atm.

We had to use the following solution https://github.com/evcohen/eslint-plugin-jsx-a11y/issues/402#issuecomment-368305051, but it would be nice to have other options.

@renet build the Link we want from the Link we get The limitation is – it breaks styled-jsx for a, so you’d need an alternative CSS-in-JS solution.

"jsx-a11y/anchor-is-valid": [
  "error",
  {
    "components": ["Link"]
  }
],
"jsx-a11y/anchor-has-content": [
  "error",
  {
    "components": ["Link"]
  }
]
import NextLink, { LinkProps as NextLinkProps } from "next/link";
import { ComponentProps } from "react";

export interface LinkProps
  extends NextLinkProps,
    Omit<ComponentProps<"a">, keyof NextLinkProps> {}

export const Link = ({
  href,
  as,
  replace,
  scroll,
  shallow,
  passHref,
  prefetch,
  ...rest
}: LinkProps) => (
  <NextLink
    href={href}
    as={as}
    replace={replace}
    scroll={scroll}
    shallow={shallow}
    passHref={passHref}
    prefetch={prefetch}
  >
    {/* href is passed by NextLink */}
    {/* eslint-disable-next-line jsx-a11y/anchor-is-valid, jsx-a11y/anchor-has-content */}
    <a {...rest} />
  </NextLink>
);

Isn’t this a limitation of styled-jsx? Anchor rendered by Links wouldn’t have styles applied.

I have a question regarding this issue:

Omitting the a-tag and only having text inside the Link Component seems to work, because of the following part of the code for next/link:

    // Deprecated. Warning shown by propType check. If the childen provided is a string (<Link>example</Link>) we wrap it in an <a> tag
    if (typeof children === 'string') {
      children = <a>{children}</a>
    }

What are the downsides to using this as a workaround? Styled-jsx was already mentioned above and it’s also not possible to give the Link-Component a class.

P.S.: The comment says, Warning shown by propType check., but there is no warning shown for me (with typescript).