Step by Step

How to add a skip link: the HTML code and the keyboard test

6 min read
Mikhail ShaymardanovWeb Quality and Accessibility Expert

A skip link is a “Skip to main content” link at the very top of the page: someone using the keyboard presses Enter and lands in the content without tabbing through the whole menu. It takes one line of HTML and a few lines of CSS, no JavaScript. Here is the code to copy, and the three-key test that tells you whether it works from the keyboard.

From the template to the three-key test


Without a skip link, anyone who moves through the page with Tab has to get past the whole header on every page. The W3C, which publishes the web accessibility guidelines (WCAG), talks about dozens of keystrokes before the main content: slow going, and physically painful for some people.

The code has three parts: a link to #main-content at the start of <body>, id="main-content" on <main>, and a CSS rule that hides the link until it gets focus. The GOV.UK Design System places the link right after the opening <body> tag, or right after the cookie banner when there is one. The link points to <main>, the element that holds the page's main content. WordPress adds this link itself as soon as a block theme's template contains <main>, and a template without one leaves all its pages without it.

<body>
  <a class="skip-link" href="#main-content">Skip to main content</a>
  <header>…</header>
  <main id="main-content">…</main>
</body>

The link can stay visible all the time, or show up only when it gets focus, that is, when Tab reaches it. A link that's always visible helps more people: keyboard users also include people who rely on screen magnification or voice control. In our example, Valcerne Mountain Guides shows it on focus. For its focus outline, see our entry on focus.

With display: none or the hidden attribute, the browser lays out the page as if the link weren't there, so it can't take focus. visibility: hidden blocks focus too: in all three cases, Tab skips the link.

The WebAIM Million 2026 looked at the home pages of the million most popular websites. One skip link in ten was broken, either hidden in a way that made it inaccessible or pointing to a target missing from the page. To hide yours, use a visually hidden technique, which takes the link off the screen but keeps it reachable from the keyboard, and undo it when the link gets focus.

Avoid

Screenshot: the Valcerne Mountain Guides header, with the red focus outline around the logo.Marker 1. The Valcerne logo, which gets focus on the first press of Tab.
.skip-link {
  display: none;
}

Correct

Screenshot: the “Skip to main content” link, white on black, at the top left of the header, with the red focus outline around it.Marker 1. The “Skip to main content” link, shown over the logo on the first press of Tab.
.skip-link {
  position: absolute;
  top: 1rem;
  left: 1rem;
  z-index: 100;
  clip-path: inset(50%);
  width: 1px;
  height: 1px;
  overflow: hidden;
  white-space: nowrap;
}
 
.skip-link:focus {
  clip-path: none;
  width: auto;
  height: auto;
  padding: 0.75rem 1rem;
  background: #111111;
  color: #ffffff;
  box-shadow: 0 6px 18px rgb(0 0 0 / 0.35);
}
On the first Tab, with display: none, focus skips the link and lands on the Valcerne logomarker 1; with the visually hidden technique, “Skip to main content”marker 1 appears over the header.
“Read more” links: make them accessible without changing the design

#Why the page scrolls but the next Tab goes back to the header?

A smooth-scroll script catches the click and scrolls the page to the target itself, so the browser never follows the link. Focus stays on “Skip to main content”, and the next Tab heads back into the header. Try it below, or open the page with the script.

Click the demo, then press the key shown, or move on with “Next step”. Escape leaves the demo.
3 steps

On the Valcerne Mountain Guides page with the script, the second Tab puts focus on the logo and scrolls the page back up: the script canceled the jump to the content.

Since 2016, when someone follows a link to an anchor like #main-content, the HTML specification requires the browser to move the starting point of keyboard navigation to the target. The next Tab starts from there in the tab order.

The smooth-scroll script calls preventDefault(), which stops the browser from following the link. The starting point never moves, so Tab goes to the element right after the link: the logo.

Remove the script and put scroll-behavior: smooth on html, the root element. That property smooths the scroll when the page jumps to an anchor. Set on body, it doesn't apply to the page's scrolling. Wrap it in @media (prefers-reduced-motion: no-preference), so people who turned on reduced motion on their device still get an instant jump.

Avoid

Screenshot: the top of the Valcerne page, with the red focus outline around the logo, above the band of today's conditions.Marker 1. The Valcerne logo, which gets focus on the second press of Tab.
document.querySelectorAll('a[href^="#"]').forEach((link) => {
  link.addEventListener("click", (event) => {
    event.preventDefault();
    document
      .querySelector(link.getAttribute("href"))
      .scrollIntoView({ behavior: "smooth" });
  });
});

Correct

Screenshot: the heading “Intro to ice climbing” and its paragraph, with the red focus outline around the “gear list” link.Marker 1. The “gear list” link, the first link in the main content, which gets focus on the second press of Tab.
@media (prefers-reduced-motion: no-preference) {
  html {
    scroll-behavior: smooth;
  }
}
On the second Tab, with the script, focus goes back to the Valcerne logomarker 1; with scroll-behavior in CSS, it enters the content, on the “gear list” linkmarker 1.

For the keyboard, no: the HTML specification already requires the browser to move the starting point of keyboard navigation to the target. tabindex="-1" is no longer what makes the link work from the keyboard. A script that focuses an element itself still needs it, such as one that moves focus to the new heading after a React Router link. A 2016 Chrome blog post still asked for it while some browsers lacked that starting point. With a screen reader, nothing guarantees that reading picks up at the target without tabindex: test that separately, for example with NVDA.

The attribute has a side effect: <main> takes focus on a mouse click inside it, and an outline appears around it if your focus style targets :focus. The 2016 post advised removing that outline.


For each page template, load a page whose main content has a link, a button or a field, with the cookie banner closed. On a page without one, or with the banner still open, the test can fail even though the link works. Press Tab, Enter, Tab: the second Tab must land in the main content. Don't click in the page along the way, since a click also moves the starting point of keyboard navigation.

Click the demo, then press the key shown, or move on with “Next step”. Escape leaves the demo.
3 steps

On the Valcerne Mountain Guides page without the script, the second Tab lands on “gear list”, the first link in the main content: the browser made the jump.

With or without the script, the page scrolls, so only the second Tab shows whether the link works. If focus goes back to the header, check that <main> has id="main-content" and that no script catches the click. If a sticky header covers the top of the content, set scroll-padding-top on html to reserve its height. The code is in our section on sticky headers.

WCAG asks every page for a way past the content repeated across a site. With your skip link in place, check these points on each template.

Safari on a Mac skips every link on Tab, “Skip to main content” included, unless one setting is on. Turn on “Press Tab to highlight each item on a webpage” in Safari > Settings > Advanced. With it off, Option+Tab reaches links.

Screenshot: the Accessibility row of Safari's Advanced settings, with “Press Tab to highlight each item on a webpage” checked.Marker 1. The “Press Tab to highlight each item on a webpage” checkbox, turned on, with the note on Option+Tab below it.
In Safari's Advanced settings, the checked boxmarker 1 makes Tab go through links; Safari notes below it that Option+Tab then highlights only text fields and pop-up menus.

The three-key test covers the keyboard. A full accessibility audit also checks reading with screen readers, and Includdy runs these audits.


Share this article

Frequently asked questions

Yes. Both names describe a link at the top of the page that jumps to the start of the main content, as WebAIM puts it. “Skip navigation” names what the link jumps over; “skip to main content” names where it lands.

For the visible text, use the second. The W3C technique for this link checks that its text says it leads to the main content.

No. Success criterion 2.4.1, Bypass Blocks, asks for a way to bypass blocks of content repeated from page to page. A link at the top of the page to the main content is one; ARIA landmarks or headings at the start of each section are others.

In the United States, the ADA rule that covers state and local governments makes WCAG its technical standard. In Europe, EN 301 549, the standard written for the European Accessibility Act, also takes its web requirements from these guidelines.

Without tabindex, <main> can't take focus: the browser gives focus to the page itself, and document.activeElement returns body. The browser still moves the starting point of keyboard navigation to <main>, so the next Tab starts from there.

To check the link, close the cookie banner and rely on Tab, Enter, Tab: if the main content has a link, a button or a field, the second Tab must land on it.