Accessibility Developer Kit · Guide 02 / 20
Links are for navigation; buttons are for actions. This guide covers native internal links, external links in a new tab, download links, and the common link-vs-button mistake — in Vanilla and React.
Links that are keyboard-friendly, screen-reader-friendly, and that tell users where they will go.
A link is one of the oldest HTML elements and still one of the most frequently misused. We will cover three valid link types (internal, external, download) and the single most common mistake: using a link to perform an action instead of a button.
Switch between the inaccessible version and the accessible fix.
Native link — browser handles focus, Enter key, right-click, and SR semantics.
<!-- Link text describes the destination; works out of context -->
<p>Check out our <a href="/pricing">pricing plans</a>.</p>Describe the destination in the link text. Avoid "click here" and "read more" — screen reader users browse by link list.
Opens in a new tab. The icon is decorative; the SR-only text announces the behavior.
<!-- rel="noopener noreferrer" + visible/SR announcement of new tab -->
<a
href="https://example.com"
target="_blank"
rel="noopener noreferrer"
>
External docs
<svg aria-hidden="true" focusable="false"><!-- external icon --></svg>
<span class="sr-only">(opens in a new tab)</span>
</a>Add rel="noopener noreferrer" for safety, plus a visible icon and SR-only text to announce the new tab.
File type and size shown in the link text so users know what to expect before clicking.
<!-- download attribute + file format and size in the label -->
<a href="/files/report.pdf" download>
Download Q4 report (PDF, 1.2 MB)
</a>Use the download attribute and include file format and size in the link text so users know what to expect.
Activated 0 times — SR says: 'Save settings, link'
<!-- Use a real button for actions. Links navigate; buttons act. -->
<button type="button" onclick="handleSave()">
Save settings
</button>Right-clicking an action-link gives you a useless '#' URL and the SR announces 'link'. Use a real button.
One component, three link types.
import React from "react";
import { ExternalLink, Download } from "lucide-react";
import "./AccessibleLink.css";
/**
* AccessibleLink
* - href : destination (required)
* - children : visible label (required, describe the destination)
* - external : opens in new tab (adds rel, icon, SR-only text)
* - download : treat as download; shows a download icon
* - fileMeta : "(PDF, 1.2 MB)" when download=true
*/
export default function AccessibleLink({
href,
children,
external = false,
download = false,
fileMeta,
className = "",
...rest
}) {
const linkClass = [
"link",
external && "link--external",
download && "link--download",
className,
]
.filter(Boolean)
.join(" ");
return (
<a
href={href}
className={linkClass}
{...(external && {
target: "_blank",
rel: "noopener noreferrer",
})}
{...(download && { download: true })}
{...rest}
>
{download && <Download aria-hidden="true" size={14} />}
<span>{children}</span>
{fileMeta && <span className="link__meta">{fileMeta}</span>}
{external && (
<>
<ExternalLink aria-hidden="true" size={14} />
<span className="sr-only">(opens in a new tab)</span>
</>
)}
</a>
);
}import AccessibleLink from "./AccessibleLink";
export default function Demo() {
return (
<>
{/* Internal link */}
<AccessibleLink href="/pricing">pricing plans</AccessibleLink>
{/* External link (new tab) */}
<AccessibleLink href="https://www.w3.org/WAI/WCAG22/" external>
WCAG 2.2 reference
</AccessibleLink>
{/* Download link with file metadata */}
<AccessibleLink
href="/files/report.pdf"
download
fileMeta="(PDF, 1.2 MB)"
>
Download Q4 report
</AccessibleLink>
</>
);
}Note: links fire on Enter only, not Space (unlike buttons).
| Key | Expected result |
|---|---|
| Tab | Link receives visible focus |
| Enter | Follows the link |
| Space | No effect on native links. If you need Space to activate, use a button. |
| Shift + F10 / right-click | Opens the context menu (Copy link, Open in new tab, etc.) |
Screen reader users often navigate by link list. Make each link make sense out of context.
Why each rule matters here.
| Success Criterion | Why it matters |
|---|---|
| 1.4.1 Use of Color (A) | Links must not rely on color alone. Add underline or icon. |
| 2.4.4 Link Purpose (In Context) (A) | Link text — plus its surrounding context — must identify the destination. |
| 2.4.7 Focus Visible (AA) | Keyboard focus must be visible on every link. |
| 3.2.5 Change on Request (AAA) | Opening a new tab unexpectedly is a context change — warn users first. |
| 1.4.11 Non-text Contrast (AA) | Focus ring must have 3:1 contrast against background. |
Framework-agnostic patterns. Pick the one that matches your stack.
The pattern is the same across frameworks: render → axe check → assert href + role + name.
// Jest + @testing-library/react + jest-axe
import { render, screen } from "@testing-library/react";
import { axe, toHaveNoViolations } from "jest-axe";
import AccessibleLink from "./AccessibleLink";
expect.extend(toHaveNoViolations);
test("renders with correct href and accessible name", () => {
render(<AccessibleLink href="/pricing">pricing plans</AccessibleLink>);
const link = screen.getByRole("link", { name: "pricing plans" });
expect(link).toHaveAttribute("href", "/pricing");
});
test("external link opens in new tab with rel noopener", () => {
render(
<AccessibleLink href="https://example.com" external>
docs
</AccessibleLink>
);
const link = screen.getByRole("link", { name: /docs/i });
expect(link).toHaveAttribute("target", "_blank");
expect(link).toHaveAttribute("rel", "noopener noreferrer");
});
test("has no axe violations", async () => {
const { container } = render(
<AccessibleLink href="/pricing">pricing plans</AccessibleLink>
);
expect(await axe(container)).toHaveNoViolations();
});// Vitest + @testing-library/react
import { expect, test } from "vitest";
import { render, screen } from "@testing-library/react";
import AccessibleLink from "./AccessibleLink";
test("external link exposes new-tab affordance", () => {
render(
<AccessibleLink href="https://example.com" external>
docs
</AccessibleLink>
);
expect(
screen.getByText(/opens in a new tab/i, { selector: ".sr-only" })
).toBeInTheDocument();
});// Playwright + @axe-core/playwright
import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";
test("link page has no serious a11y violations", async ({ page }) => {
await page.goto("/en/accessible-link");
const results = await new AxeBuilder({ page })
.withTags(["wcag2a", "wcag2aa", "wcag22aa"])
.analyze();
const serious = results.violations.filter(
(v) => v.impact === "critical" || v.impact === "serious"
);
expect(serious).toEqual([]);
});
test("external link opens a new tab", async ({ page, context }) => {
await page.goto("/en/accessible-link");
const [newTab] = await Promise.all([
context.waitForEvent("page"),
page.getByRole("link", { name: /WCAG 2.2/i }).click(),
]);
await newTab.waitForLoadState();
expect(newTab.url()).toContain("w3.org");
});Tick each item before shipping.
The link bugs we see on 80% of audits.
Grab the code bundle, or jump to the next guide.
