
The `aria-label` property can be extremely useful when used correctly. When used incorrectly, it can wreak havoc on speech-input user experiences. It's an easy mistake to make and luckily it's pretty easy to fix!

## What is the `aria-label` property?

As defined by the WAI ARIA 1.2 standards, [the `aria-label` property](https://www.w3.org/TR/wai-aria-1.2/#aria-label) "defines a string value that labels the current element". It has the same purpose as [the `aria-labelledby` property](https://www.w3.org/TR/wai-aria-1.2/#aria-labelledby), which references another element that labels the current element. The purpose of both of these properties is to provide an [Accessible Name](https://www.w3.org/TR/accname-1.1/#dfn-accessible-name) of the current element.

Related to these properties is the `aria-describedby` property, which references another element that describes the current element. The purpose of this property is to provide an [Accessible Description](https://www.w3.org/TR/accname-1.1/#dfn-accessible-description) for the current element. The Accessible Name should be short and concise, and the Accessible Description should be more verbose and complement the Accessible Name.

The Accessible Name is part of what screen readers use to announce elements to a user when they come into focus. A `<button>` with no `aria-label` and plain text between its opening and closing tags would have an Accessible Name that matches its plain text. That same `<button>` can have its Accessible Name overridden with something completely different using the `aria-label` property.

Use the next two example code snippets to compare how the same button sounds with and without an `aria-label`.

<CallOut id="example-1" title="Example 1: <button> with no aria-label" type="example">

The code:

```html
<button>OK</button>
```

The output:

<br />
<button>OK</button>

</CallOut>

<CallOut id="example-2" title="Example 2: <button> with an aria-label" type="example">

The code:

```html
<button aria-label="Confirm selection">OK</button>
```

The output:

<br />
<button aria-label="Confirm selection">OK</button>

</CallOut>

## Why does `aria-label` need to match the visible label?

First of all, an `aria-label` must match its element's visible label because there is a Level A WCAG Success Criterion that says so. [SC 2.5.3: Label in Name](https://www.w3.org/TR/WCAG21/#label-in-name) says:

> For user interface components with labels that include text or images of text, the name contains the text that is presented visually.

This means that the Accessible Name computed for an element should contain the text of the element's visual label. One best practice for this is to have the Accessible Name start with the visual label's text. So if a link contains the text "Learn more" and the author of that link wants to include more information about the link's purpose in the `aria-label`, a good practice is to start the `aria-label` with "Learn more".

If you're like me and my ADHD brain, you might need a little more reasoning than "the rules say so" to motivate you to follow the rules. A lot of people don't like being told what to do, and that's fine!

So why do we need to follow Success Criterion 2.5.3? It partially has to do with speech-recognition technology. As it turns out, the Accessible Name for elements is how speech-input users can interact with elements in a web page.

Referencing our two previous examples:

- A speech-input user can activate the button from [Example 1](#example-1) by saying "Click OK". This is because the Accessible Name for that button is "OK".
- A speech-input user cannot activate the button in [Example 2](#example-2) in the same way. This is because the Accessible Name for that button is "Confirm selection". If a speech-input user wanted to activate this button, they would have to say "Click confirm selection".

For speech-input users that rely on visual labels to come up with voice commands, there no way for them to know before speaking a command if the Accessible Name of an element differs from its visual label. They will have to speak a command and find out if it does or does not work. If a command doesn't work, they may retry a couple of times. And if the command actually does not work at all because the Accessible Name doesn't match the visual label, their energy has been wasted and they're also stuck.

## What happens when `aria-label` doesn't match the visible label?

As I wrote this article, I started to learn about Voice Control on Mac. I wanted to see if I could find a real world example of speech-input navigation being broken due to mismatched visual labels and accessible names. I found a couple of examples right on the Twitter home page.

Unfortunately, more than half of the main navigation links have accessible names that don't match their visual labels. Even in the cases where a link's `aria-label` began with the text in the visual label, I was not successful in activating those links with speech-input. I made countless attempts.

- Home: The `aria-label` for this link is dynamic. If there are unread tweets in a user's feed, then the `aria-label` reads "Home (New unread Tweets)". The "Click Home" command only activates this link if there are no unread tweets.
- Explore: The `aria-label` for this link is "Search and explore". Saying "Click Explore" does not activate this link.
- Notifications: The `aria-label` for this link is dynamic. If a user has 2 notifications for example, the `aria-label` is "Notifications (2 unread notifications)". The "Click Notifications" command only activates this link if a user has 0 unread notifications.
- Messages: The `aria-label` for this link is dynamic. If a user has unread messages from one other user, for example, the `aria-label` is "Direct Messages (1 unread conversation)". If there are no unread messages, the `aria-label` is "Direct Messages". The "Click messages" command does not ever work.

Here's a quick demo of me trying to activate the "Messages" link that shows on the home page of Twitter:

<iframe
  title="Voice Control Demo - Twitter Messages link"
  width="100%"
  height="350"
  src="https://www.youtube-nocookie.com/embed/FBiKOt-ipO0"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>

## Are there other users that benefit from `aria-label` matching the visible label?

This article primarily focuses on the sighted speech-input user's experience, but there are other users affected by this issue as well. Think of a sighted screen reader user that comes across the `<button>` element in [Example 2](#example-2). It is presented by their screen reader as "Confirm selection, button", but the text in the button says "OK".

This can be a very confusing and stressful experience for the user. How can they be certain the issue is with the website and not their own action? We're imposing an extra cognitive load on the user to process the mismatched audio and visual experiences. There is also extra cognitive load required to first memorize the behavior, and then recall it the next time they come across the element.

It's not necessary or kind to do this to users. It's energy-draining, and energy is an extremely limited resource for all kinds of people who rely on accessible interfaces.

## How do I fix mismatched `aria-label`s and visual labels?

Now that you know mismatching `aria-label` and visual labels is harmful for speech-input users, how do you go about preventing that harm? First, I'd recommend reading [Playing with state](https://sarahmhigley.com/writing/playing-with-state/) by Sarah Higley and [Be Careful with Dynamic Accessible Names](https://adrianroselli.com/2020/12/be-careful-with-dynamic-accessible-names.html) by Adrian Roselli.

Second, think about whether or not you need to provide an `aria-label` for the element that differs from its visual label. Some cases that come to mind:

- Are there duplicate visual labels?
  - Your markup can generally be improved by ensuring all visual labels are unique. This is beneficial for screen reader navigation.
  - The speech recognition technology probably has a way to help the user choose which element they want. With Voice Control on Mac, a number appears next to the elements with matching Accessible Names after the command is spoken. Then you're able to say the number of the element you want to activate.
- Is the content of the element plain text? Omit the `aria-label` property. The computed accessible name for the element will be its text content.
- Is the element a toggle button? Reference the [Playing with state](https://sarahmhigley.com/writing/playing-with-state/) article I mentioned and also check out the [Toggle Buttons](https://inclusive-components.design/toggle-button/) writeup from Inclusive Components. The `aria-pressed` property better suits your needs than a dynamic `aria-label`.

After you've spent time thinking thoroughly about your `aria-label`s and visual labels, make the updates and **test them with your users**. It's hard for us to know if something is usable if it doesn't intersect with our own needs. The only experiences we can truly be experts of are our own. Don't miss the step where you get your information from the source of truth: your users with expertise in their lived experiences.


Users suffer when the accessible name of an element doesn’t match its visual label.

Don’t Overwrite Visual Labels With `aria-label`

Despite being answered time and time again, the button vs. link question prevails.

Should I Use a Button or a Link?

If you've been working in web accessibility for a while, you know there are many foundational quick-wins that can go a long way. If you're new to web accessibility, hopefully this doesn't come as a surprise! There are definitely challenging aspects to web accessibility, but it's not all that way. And lucky for us, a lot of the quick-wins are also quick and easy to identify with some automated tools! [`pa11y-ci`](https://github.com/pa11y/pa11y-ci) is just one of those tools.

In this post, I'll show you how I set up a [GitHub Action](https://github.com/features/actions) that runs `pa11y-ci` as a pull request check. The check will run against a Vercel deploy preview, and then the results will be shared as a comment on the pull request for easy visibility.

If at any point you find yourself stuck or needing to troubleshoot, check out a GitHub repository I created that represents the end-result of this guide: https://github.com/ashleemboyer/pa11y-ci-test-app.

## Step 1 (optional): Create a Next.js App

If you don't already have a Next.js App to follow along with, I recommend creating one. There are multiple ways of doing this detailed on [the Next.js Getting Started page](https://nextjs.org/docs/getting-started). To keep things simple for this example, I'm using the Automatic Setup approach.

**To create the Next.js app:**

1. Open a terminal
2. Run `npx create-next-app@latest`
3. When prompted, name the app `pa11y-ci-test-app`
4. Change directory into the new folder: `cd pa11y-ci-test-app`
5. Briefly explore the code and learn your way around

Note: I will be using `npm` instead of `yarn` for the rest of this post. If your generated project uses `yarn`, and you would also like to to use `npm` instead:

1. Run `rm yarn.lock` to delete the file
2. Run `npm install` to create a `package-lock.json` file
3. Run `npm run build` so the `package-lock.json` file can be patched if needed
4. Run `npm install` one more time to download any missing dependencies
5. Run `git add .` to stage the changed files for a commit
6. Run `git commit -m "Using npm instead of yarn"` to commit the changes

## Step 2 (optional): Create and Connect a GitHub Repository

If you followed step 1 and created a new Next.js App, you should follow this step as well. You will need a GitHub Repository for your project in order to run the GitHub Action we're creating.

**To create the GitHub Repository:**

1. Go to [github.com/new](https://github.com/new)
2. If needed, log in to your account
3. Under "Owner", select your account
4. Under "Repository name", enter `pa11y-ci-test-app`
5. Select either "Public" or "Private"
6. Click the "Create repository" button
7. Leave this page open in your browser

**To connect the GitHub Repository to your project:**

1. In a terminal, go to your project folder
2. Run `git remote add origin git@github.com:<YOUR-USERNAME>/pa11y-ci-test-app.git` after replacing `<YOUR-USERNAME>` with the GitHub username you used to create the repository. (Read about [Working with Remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) and [Remote Branches](https://git-scm.com/book/en/v2/Git-Branching-Remote-Branches) if you're curious.)
3. Run `git push -u origin main` to push the code to the repository.
4. Verify these steps were successful by refreshing your new repository's page in your browser

## Step 3: Install and Configure `pa11y-ci`

It's always good to test new tools locally (on your machine) before testing them remotely in a place like a pull request. Testing remotely can be tedious and time consuming, and the results of the testing can also be more difficult to locate and read. And if you happen to be like me and have ADHD, all of that is a recipe for multiple distractions!

Before doing anything else, let's create a new git branch. That will be useful later when we need to create a pull request for our GitHub Action.

**To create a new `git` branch:**

1. In a terminal, go to your project folder
2. Run `git checkout -b add-pa11y-ci`

**To install `pa11y-ci`:**

1. In a terminal, go to your project folder
2. Run `npm install --save-dev pa11y-ci`
3. Open the `package.json` file in your project
4. Verify the `pa11y-ci` package is listed under `devDependencies`

**To configure `pa11y-ci` for local testing:**

1. In your project folder, create a file called `.pa11yci`
2. In the new file, paste the following JSON:

```json
{
  "urls": ["http://localhost:3000/"]
}
```

This configuration tells `pa11y-ci` exactly what `urls` in our app it needs to test.

## Step 4: Test `pa11y-ci` locally (on your machine)

Now that we have `pa11y-ci` installed and configured for local testing, we can get to testing!

1. In your project folder, open the `package.json` file
2. Under the `"scripts"` property, add a new entry: `"pa11y-ci": "pa11y-ci"`
3. Open two separate terminals to your project folder
4. In the first terminal, run `npm run dev` to start the app
5. In the second terminal, run `npm run pa11y-ci` to run the new script we added in step 2

After `pa11y-ci` has finished running, this is how the output should read:

```
> pa11y-ci-test-app@0.1.0 pa11y-ci
> pa11y-ci

Running Pa11y on 1 URLs:
 > http://localhost:3000/ - 1 errors

Errors in http://localhost:3000/:

 • The html element should have a lang or xml:lang attribute which describes the language of the document.

   (html)

   <html><head><meta name="viewport" con...</html>

✘ 0/1 URLs passed
```

Hooray! We have an error, but the good news is that means `pa11y-ci` is working! Now we can progress from local testing towards creating our GitHub Action.

## Step 5: Deploy to Vercel

Our current configuration for `pa11y-ci` only works for when we run our app locally with `npm run dev`. For remote testing, we want `pa11y-ci` to test against real builds and public-facing urls. In order to do that, we need to deploy our Next.js app. We'll use Vercel in this example.

**How to deploy to Vercel:**

1. Go to [vercel.com/new](https://vercel.com/new)
2. If needed, log in to your account
3. Under "Import Git Repository", select "Continue with GitHub"
4. Search for your new repo (mine is called `pa11y-ci-test-app`)
5. Click the Import button in-line with the repo name
6. Click the Deploy button (you should not need to change any configuration)

Once the deploy is complete, you can close this window.

## Step 6: Install and Configure `next-sitemap`

There's another way `pa11y-ci` can be used to test against urls, and that is with the `--sitemap` option. This option is nice when you have a `sitemap.xml` file on your site that updates every time a build occurs. It means you don't have to manually update the `.pa11yci` file's list of urls every time a new page is added. The tool we'll use for generating a `sitemap.xml` file is called [`next-sitemap`](https://www.npmjs.com/package/next-sitemap), which is the tool I use on my own website for `pa11y-ci` testing.

**To install `next-sitemap`:**

1. In a terminal, go to your project folder
2. Run `npm install next-sitemap`

**To configure `next-sitemap`:**

1. In your project folder, create a new file called `next-sitemap.config.js`
2. In the new file, paste the following JavaScript:

```javascript
module.exports = {
  siteUrl: process.env.VERCEL_URL
    ? `https://${process.env.VERCEL_URL}`
    : 'http://localhost:3000/',
};
```

This tells `next-sitemap` what the main url of your site is. If you use a different port number than `3000`, make sure to update the code above to match the port number you use.

## Step 7: Test `next-sitemap` locally (on your machine)

To make sure we have everything configured correctly, we're going to test `next-sitemap` locally just like we did with `pa11y-ci`.

1. In your project folder, open the `package.json` file
2. Under the `"scripts"` property, add a new entry: `"postbuild": "next-sitemap"`
3. In a terminal, go to your project folder
4. Run `npm run build`

The new `postbuild` script we added will run automatically after the `build` script has completed. You should see some new `sitemap` files in the `public` directory. We will add those to the `.gitignore` file in the next section.

You should also see something like this output in the terminal after the `build` script output:

```
> pa11y-ci-test-app@0.1.0 postbuild
> next-sitemap

✨ [next-sitemap] Loading next-sitemap config: file:///pa11y-ci-test-app/next-sitemap.config.js
✅ [next-sitemap] Generation completed
┌───────────────┬────────┐
│    (index)    │ Values │
├───────────────┼────────┤
│ indexSitemaps │   1    │
│   sitemaps    │   1    │
└───────────────┴────────┘
-----------------------------------------------------
 SITEMAP INDICES
-----------------------------------------------------

   ○ http://localhost:3000/sitemap.xml


-----------------------------------------------------
 SITEMAPS
-----------------------------------------------------

   ○ http://localhost:3000/sitemap-0.xml
```

## Step 8: Prepare for and Create a New Pull Request

Hopefully you created a new git branch called `add-pa11y-ci` [in Step 3](#step-3-install-and-configure-pa11y-ci), but it's also okay if you didn't! Go ahead and create it now. We'll need a different branch off of the main one in order to create a pull request in our GitHub repository.

**To prepare for the pull request:**

1. Make sure there is a `/public/sitemap*` entry in the `.gitignore` file. We **do not** want to commit these files since they need to be generated by the Vercel build process.
2. Make sure you have all your new `pa11y-ci` and `next-sitemap` work committed. I'm committing everything at once with the message: `"Adding pa11y-ci and next-sitemap"`.
3. Run `git push --set-upstream origin add-pa11y-ci` to push your new branch up to the repository.

**To create the new pull request:**

1. Go to `github.com/<YOUR-USERNAME>/pa11y-ci-test-app/compare` after replacing `<YOUR-USERNAME>` with the GitHub username you used to create the repository
2. Change the `compare` branch to `add-pa11y-ci`
3. The page should update have at least these 5 changed files:
   - `.gitignore`
   - `.pa11yci`
   - `next-sitemap.config.js`
   - `package-lock.json`
   - `package.json`
4. Click the "Create pull request" button
5. You should see 2 text boxes: one for the name of the pull request and one for the description
6. Fill in the title and description however you need
7. Click "Create pull request"

**To verify everything is set up correctly:**

1. Wait for the `vercel` bot to comment on the new pull request
2. In the new comment, open the "Visit Preview" link in a new tab
3. You should see your app built and running
4. Go to the `/sitemap.xml` page in the same app
5. You should see an XML file with contents that look something like this:

```xml
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <sitemap>
    <loc>YOUR-APP-URL/sitemap-0.xml</loc>
  </sitemap>
</sitemapindex>
```

## Step 9: Create the pa11y-ci GitHub Action

Now that we have a live website to have `pa11y-ci` test against, we can create the GitHub Action that runs `pa11y-ci`.

**To create the GitHub Action:**

1. In your project folder, create a new folder called `.github`
2. In the new `.github` folder, create another folder called `workflows`
3. In the new `workflows` folder, create a new file called `pa11y-ci.yml`
4. Paste the following content in your new file:

```yml
# Wait to run until after the Vercel deployment has finished
# https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#deployment_status
on: deployment_status

jobs:
  pa11y-ci:
    # Only run if the Vercel deployment was successful
    # https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#deployment_status
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest

    steps:
      # Checkout latest commit of repo
      # https://github.com/actions/checkout#checkout-v3
      - uses: actions/checkout@v3

      # Install project dependencies
      - run: npm install

      # Run pa11y-ci against the generated sitemap
      # https://github.com/pa11y/pa11y-ci#sitemaps
      - run: npm run pa11y-ci -- --sitemap ${{ github.event.deployment_status.target_url }}/sitemap.xml
```

Before committing and pushing this new file, make sure to delete the `.pa11yci` file. It's no longer needed.

**To verify the GitHub Action works:**

1. Commit and push the new `.github/workflows/pa11y-ci.yml` and the removed `.pa11yci` file
2. Go to your pull request in a browser
3. Towards the bottom of the page, wait until you see the `pa11y-ci` check finish
4. The check should fail
5. Click the "Details" link to inspect the failed check
6. You should see the same error that you saw when testing locally in [Step 4](#step-4-test-pa11y-ci-locally-on-your-machine)

## Step 10 (optional): Update the pa11y-ci GitHub Action to add a comment on pull requests

When I added this `pa11y-ci` GitHub Action to my own site's pull requests, I decided to make it also comment results on the pull request. There are a couple of reasons for this:

- Normally you have to click the "Details" link next to a failed pull request check. This takes you to another page and away from the pull request. For me, that means an opportunity to get easily distracted.
- The formatting of results in pull request checks can sometimes be difficult to read. Putting the results in a pull request comment gives an opportunity to re-format them in a more readable way.

So to update the GitHub Action to comment on pull requests, we'll need to tell the `pa11y-ci` command to output its results in a different way, and then we'll add a step to the GitHub Action that reads the output, formats it, and creates a comment.

1. Update the `pa11y-ci` `run` step in `.github/workflows/pa11y-ci.yml` to be:
   ```yml
   # Run pa11y-ci against the generated sitemap
   # https://github.com/pa11y/pa11y-ci#sitemaps
   - run: npm run pa11y-ci -- --json --sitemap ${{ github.event.deployment_status.target_url }}/sitemap.xml |& tee pa11y-output.txt
   ```
2. Add a new step at the end of the file like this:
   ```yml
   # Comment the formatted pa11y-ci results on the PR
   - uses: actions/github-script@v5
     env:
       BODY_PREFIX: ''
     with:
       script: |
         const script = require('./.github/workflows/scripts/pa11y-ci.js')
         await script({ context, core, github })
   ```
3. Add a new folder inside `.github/workflows` called `scripts`
4. Add a new file to `scripts` called `pa11y-ci.js`
5. In the new file, paste the following JavaScript:

   ````js
   const { promises: fs } = require('fs');

   module.exports = async ({ context, core, github }) => {
     // Find this PR & do nothing if this isn't a PR
     const { data } =
       await github.rest.repos.listPullRequestsAssociatedWithCommit({
         owner: context.repo.owner,
         repo: context.repo.repo,
         commit_sha: context.sha,
       });
     const prNumber = data[0] && data[0].number;
     if (!prNumber) {
       return;
     }

     // Read the pa11y output and build the comment body
     const pa11yOutput = await fs.readFile('./pa11y-output.txt', 'utf8');
     const lines = pa11yOutput.split('\n');
     const asJSON = JSON.parse(lines.find((line) => line.startsWith('{')));
     const { total, errors, results } = asJSON;

     let commentBody = `${process.env.BODY_PREFIX}\n<h2>:microscope: pa11y-ci results</h2>\n\n`;
     commentBody += `- Number of URLs tested: ${total}\n`;

     if (!errors) {
       commentBody += `- No errors were found! :tada:\n`;
     } else {
       commentBody += `- Number of errors found: ${errors}. :sob:\n`;

       let formattedOutput = '';
       Object.keys(results).forEach((urlKey) => {
         const errors = results[urlKey];
         if (errors.length < 1) {
           return;
         }

         formattedOutput += `- [${urlKey}](${urlKey}):\n\n`;
         errors.forEach((error) => {
           formattedOutput += '  ```\n';
           formattedOutput += `  ${error.message}\n\n`;
           formattedOutput += `  ${error.selector}\n\n`;
           formattedOutput += `  ${error.context}\n\n`;
           formattedOutput += `  ${error.code}\n`;
           formattedOutput += '  ```\n\n';
         });
       });

       commentBody += `<details><summary>See results :eyes:</summary>\n\n${formattedOutput}</details>`;
     }

     // Get the comments on this PR
     const { data: comments } = await github.rest.issues.listComments({
       owner: context.repo.owner,
       repo: context.repo.repo,
       issue_number: prNumber,
     });

     // Try to find an existing pa11y results comment
     const previousComment = comments.find((comment) =>
       comment.body.startsWith(process.env.BODY_PREFIX),
     );
     if (previousComment) {
       // Update the previous comment
       await github.rest.issues.updateComment({
         owner: context.repo.owner,
         repo: context.repo.repo,
         comment_id: previousComment.id,
         body: commentBody,
       });
     } else {
       // Create a new comment
       await github.rest.issues.createComment({
         owner: context.repo.owner,
         repo: context.repo.repo,
         issue_number: prNumber,
         body: commentBody,
       });
     }

     if (errors) {
       core.setFailed('Errors were found by pa11y-ci');
     }
   };
   ````

6. Commit and push the changes to `.github/workflows/pa11y-ci.yml` and the new `.github/workflows/scripts/pa11y-ci.js` file.

**To verify that everything is working as expected:**

1. Go to your pull request in your browser
2. Wait for the `pa11y-ci` check to finish
3. The check should fail just like it did before
4. Look for a comment by the `github-actions` bot that says "🔬 pa11y-ci results"
5. The comment should say that 1 error was found
6. Expand the "See results 👀" text
7. There should be one error listed that matches the same error you've been seeing

## Step 11. Celebrate! 🎉

Nicely done! You've added a `pa11y-ci` GitHub Action that runs on pull requests. You should be proud. Give yourself a pat on the back. 😊

Use pa11y-ci to test deploy previews before merging pull requests.

How I Added a pa11y-ci GitHub Action to My Next.js Site


Many sites on the web have the same content at the top of every page. The content is commonly a logo that links to the home page and then several links to the main pages of the site. If you navigate the same site regularly, you probably find these navigation links repetitive because you learn to know what's already there. Even when you follow a link to a site you've never been to before, you probably expect there to be a set of navigation links at the top. If you're just trying to read the content of the page and don't care about the header, you'll find Skip Navigation links useful.

## What are Skip Navigation Links?

Skip Navigation Link are pretty straightforward. They enable people to skip the navigation at the beginning of a site and get to the main content of the page. This is really helpful for people who navigate sites without a pointer device, such as a keyboard. Without a Skip Navigation Link, a keyboard user would have to tab through every link, button, etc. that appears before the main page content. While tabbing might not be a difficult task for you personally, it is often more difficult for disabled users, so it's necessary to prevent that difficulty.

## Are there any guidelines for Skip Navigation Links?

Skip Navigation Links fall under [Web Content Accessibility Guideline 2.4: Provide ways to help users navigate, find content and determine where they are](https://www.w3.org/WAI/GL/WCAG20/WD-UNDERSTANDING-WCAG20-20081105/navigation-mechanisms.html). The first Success Criterion for this guideline is called [Success Criterion 2.4.1: Bypass Blocks](https://www.w3.org/WAI/GL/WCAG20/WD-UNDERSTANDING-WCAG20-20081105/navigation-mechanisms-skip.html), and within that is [Technique G1: Adding a link at the top of each page that goes directly to the main content area](https://www.w3.org/WAI/GL/WCAG20/WD-WCAG20-TECHS-20081105/G1). The writeup for Technique G1 lists the following as [requirements for Skip Navigation Links](https://www.w3.org/WAI/GL/WCAG20/WD-WCAG20-TECHS-20081105/G1#G1-procedure) that go to the main content of a page:

1. Check that a link is the first focusable control on the Web page.
2. Check that the description of the link communicates that it links to the main content.
3. Check that the link is either always visible or visible when it has keyboard focus.
4. Check that activating the link moves the focus to the main content.
5. Check that after activating the link, the keyboard focus has moved to the main content.

## What does the code look like?

I just used a little CSS and JSX for my Skip Navigation Link, and I opted for making it visible only when it gets keyboard focus. On my site, I use [Next.js Per-Page Layouts](https://nextjs.org/docs/basic-features/layouts#per-page-layouts) to help me render repeated content, such as navigation links, on many pages. The layout I use for the navigation header is where I placed a Skip Navigation Link. The code looks something like this:

```tsx
import styles from './base-layout.module.css';

const BaseLayout = ({ children }) => {
  return (
    <div className={styles.baseLayoutContainer}>
      <a className={styles.skipNavigationLink} href="#main-content">
        Skip Navigation
      </a>
      <SiteHeader />
      <main id="main-content" className={styles.mainElement} tabIndex={-1}>
        {children}
      </main>
      <SiteFooter />
    </div>
  );
};
```

What's important to note from this code:

1. The Skip Navigation Link is before the `SiteHeader` component that I built for rendering navigation links on my site. Remember: the link must be the first focusable control on the page.
2. The Skip Navigation Link's `href` property references the `id` of the `main` element where I render the content of a page.
3. The `main` element that I'm linking to with the Skip Navigation Link has `tabIndex` set to `-1`. This makes the element focusable but does not include it in the page's tab order. Further reading from TPGi: [Using the tabindex attribute](https://www.tpgi.com/using-the-tabindex-attribute/).

After I figured out the markup, I applied CSS to hide the Skip Navigation Link when not focused and also some CSS to remove the focus outline from the `main` element. The code looks something like this:

```css
.baseLayoutContainer {
  position: relative;
}

.skipNavigationLink {
  left: -10000px;
  position: absolute;
  z-index: 1;

  &:focus {
    left: 0;
  }
}

.mainElement:focus {
  outline: none;
}
```

What's important to note from this code:

1. The parent container of the Skip Navigation Link, specified by the `baseLayoutContainer` class name, has `position: relative` set. This is important because `position: absolute` is set on the Skip Navigation Link.
2. The Skip Navigation Link has `position: absolute`, `left: -10000px`, and `z-index: 1` set. This set of properties places the link off the left side of the page by 10,000 pixels and ensures it's placed on top of other elements using `z-index`. You may have to tweak this value if you have used it in other places in your app.
3. When the Skip Navigation Link is focused, the `left` position is updated to `24px`, moving it to be in view in the page.
4. When the `main` element (specified by the `mainElement` class name) is focused, `outline` is set to `none` so that no focus outline shows on the element after navigating to it with the Skip Navigation Link.

## Conclusion and Further Reading

And that's all! Skip Navigation Links are a super quick accessibility win with a ton of value since they help so many folks. Celebrate your quick win and keep the momentum going! [Consider adding a scroll-to-top link next if you haven't already](/blog/accessible-smooth-scroll-to-top-buttons-with-little-code).

### Further reading

- [Add a "Skip Navigation" Link to Help Keyboard Users Reach Main Content Faster](https://dequeuniversity.com/tips/add-skip-navigation-link)
- [Technique G123: Adding a link at the beginning of a block of repeated content to go to the end of the block](https://www.w3.org/WAI/GL/WCAG20/WD-WCAG20-TECHS-20081105/G123.html)
- [Technique G124: Adding links at the top of the page to each area of the content](https://www.w3.org/WAI/GL/WCAG20/WD-WCAG20-TECHS-20081105/G124.html)


Adding a "Skip Navigation" link is as easy as adding a few lines of code.

Ashlee M Boyer

Recommended writings

Most recent writings