# Link

> How to build an accessible link, native or custom, and the tests Evinced runs on its role, name, disabled state, focus, and keyboard activation.

Source: https://knowledge.evinced.com/web/ui-patterns/link

A link takes users to another resource, such as a page, a place on the current page, or a file. An accessible link carries the `link` role and a name that identifies its destination, and keyboard users can reach and follow it.

Whenever you can, build a link from the native HTML anchor element, `<a>`, with an `href` attribute. Browsers give it the `link` role, keyboard operation, and navigation behavior at no cost, along with the extras users expect from a link, such as opening in a new tab and copying the destination.

When a design constraint rules out a native anchor, any element can serve as a link by carrying the `link` role, but then the appearance and every behavior a browser would have supplied become your responsibility.

A link isn't the same thing as the HTML `<link>` element, which connects a document to an external resource such as a stylesheet and has no interactive presence for users. A link also differs from a button. If activating a control doesn't navigate to a new resource, such as submitting a form or opening a dialog, use a button instead.

## When to Use

Use a link when:

-   Activating it takes the user to another resource, such as a different page, a place within the current page, a document, or an external site.
-   You want the navigation behaviors browsers provide for links, including opening in a new tab, following the link from the keyboard, bookmarking, and previewing the destination on hover or focus.

Do not use a link when:

-   The control performs an action that doesn't navigate anywhere, such as submitting a form, opening a dialog, or toggling a setting. Use a button instead.
-   You want to prevent navigation to another resource by setting `href=""` or `href="#"`. Use a button or set `href` to a valid resource.
-   You need a reference to an external resource such as a stylesheet. Use the HTML `<link>` element in the document's `<head>` to include resources used to build the document.

## Examples

Code in this section is meant to demonstrate techniques rather than requirements and lacks features needed in a production application.

By default, the native HTML anchor element with a valid `href` attribute, `<a href="a_resource">`, conveys its purpose through its appearance and its `link` role, and it's keyboard accessible and operable. A custom link built from a non-semantic element needs to add the `role="link"` attribute and recreate the native anchor's appearance, focus behavior, and keyboard activation itself.

### Native HTML link

The `href` attribute sets a URL that targets an external resource or a page on the same domain. To target a specific location, append `#` followed by a valid `id`.

**Native link HTML**

```html
<!-- Link to a location on an external resource -->
<a href="https://www.w3.org/TR/wai-aria-1.3/#link">
    Accessible Rich Internet Applications (WAI-ARIA) 1.3 › link role
</a>


<!-- Relative link to another page on this domain -->
<a href="../button">Button</a>


<!-- a location on the current page -->
<a href="#structure-and-semantics">Structure and Semantics</a>
```

### Custom ARIA link

To create a custom link, add `role="link"` to an element that can accept it, and add JavaScript to recreate the necessary behavior. If the element isn't natively interactive, also set `tabindex="0"` so keyboard users can reach it.

In this example, an image becomes a link, acquiring an accessible name from its `alt` text.

**Custom link HTML**

```html
<img
    class="profile-image"
    src="/image/my-profile-pic.png"
    role="link"
    tabindex="0"
    alt="my profile"
    data-href="/profile">
```

JavaScript event listeners enable operation with either a pointer or a keyboard. Native links don't activate on Space, allowing Space to retain its default scroll behavior. Only Enter needs to be handled.

**Custom link JavaScript**

```javascript
document.querySelectorAll('[role="link"]').forEach((link) => {


  // handle pointer interaction
  link.addEventListener("click", (event) => {
      const url = event.target?.dataset.href;
      if (!url) return null;
      if (window.navigation) window.navigation.navigate(url);
      else window.location.href = url;
  });


  // handle keyboard Enter keydown
  link.addEventListener("keydown", (event) => {
    if (event.key === "Enter") {
      event.preventDefault();
      link.click()
    }
  });
});
```

CSS adds visual cues when the link has pointer hover or keyboard focus.

**Custom link CSS**

```css
img[role="link"]:hover,
img[role="link"]:focus-visible {
  cursor: pointer;
  outline: solid 2px oklch(65% 0.19 253);
}
```

## Structure and Semantics

Assistive technology exposes a link's `link` role and its accessible name, so screen reader users hear what the link does and something about where it takes them.

Without a role explicitly set, the HTML anchor element, `<a>`, exposes the `link` role when it carries an `href` attribute. Without an `href` attribute, the `<a>` element is not a link, is not interactive, and is not in the tab order.

When the native anchor element isn't possible, use an element that can accept the `link` role and explicitly set the attribute `role="link"`. Refer to [ARIA in HTML](https://www.w3.org/TR/html-aria/#docconformance) to find which elements can be used as links.

Adding `role="link"` to an element changes how assistive technology identifies it, not how it functions. For that, add JavaScript. And unless it's already an interactive element, set `tabindex="0"` to add it to the tab order.

To disable a native HTML anchor, `<a>`, the recommended method is to remove its `href` attribute, which removes its `link` role, its function, and its tab stop, so `aria-disabled` isn't needed.

Any link that keeps the `link` role while it's disabled carries `aria-disabled="true"` so that assistive technology reports it as disabled. That includes a custom link disabled in code, and an `<a>` element whose `href` is removed and that sets `role="link"` to keep its role.

### Role

A link exposes the `link` role, and it exposes it on the element the user focuses and activates. An `<a>` element with an `href` attribute carries that role implicitly, so most links satisfy this with no `role` attribute. A custom link declares `role="link"` on the same element that holds the accessible name, the tab stop, and the activation handling.

**Link has the correct role**

**Reported as:** Element has incorrect role

A link must expose the `link` role so assistive technology can convey that it navigates somewhere.

When the role is missing or wrong, the link is exposed as plain content or as the wrong kind of control, and users can't tell what activating it would do. A `<span>` or `<div>` styled to look like a link is not a link as far as assistive technology is concerned, nor is an `<a>` element without an `href`, even if it behaves like one.

When using an element other than `<a>` with an `href`, set `role="link"` so assistive technology users can also treat it as a link.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Link role applied to the interactive element**

**Reported as:** Incorrect root element

**Sanity check.** Evinced checks that the `link` role sits on the element users focus and operate, rather than on a wrapper around it or a descendant inside it. This check runs on every UI pattern, not only on links.

A link should carry the `link` role on the element users focus and operate, not on a wrapper around it or a descendant inside it.

When the role sits on one element while the tab stop and the click handling sit on another, no single element holds both the semantics and the behavior. Assistive technology describes whatever has focus, so users land on an element with no role and are told nothing about it, even though `role="link"` is in the markup.

Put the role, the accessible name, the tab stop, and the activation handling on one element, and keep any layout wrapper free of roles and handlers. If the test selected a wrapper by mistake, select the link itself and run the test again.

### Link name

Unlike a button, whose name should identify the button's action, the name of a link identifies the resource at the link's destination. A name such as "here" or "read more" tells nothing without a wider context, which screen reader users won't have when using a feature that lists every link or jumps from link to link.

Browsers compute a link's **accessible name** from its text content, the `alt` text of an image inside it, or its `aria-label` or `aria-labelledby` attribute. If `aria-labelledby` is set, its value overrides competing names. Otherwise, if `aria-label` is set, its value overrides.

The following example shows two ways to set an accessible name when the link's content is an image.

```html
<!-- The image's alt text becomes the link's accessible name -->
<a href="/about">
  <img src="./about.png" alt="About" />
</a>


<!-- Or name the link directly and hide the redundant image -->
<a href="/about" aria-label="About">
  <img src="./about.png" role="presentation" />
</a>
```

**Link has an accessible name**

**Reported as:** Accessible name

A link must have an accessible name that describes the resource it leads to.

Without an accessible name, assistive technology can only report that a link is there, so users can't tell one link from another or know anything about its destination. Voice control users don't have a name to activate it.

A link with visible text that identifies its destination works best for everyone. Screen reader users hear that name, and voice control users can speak it to activate the link. When the link contains a meaningful image, such as a profile photo that takes users to their profile or account page, give the image meaningful `alt` text or give the link an `aria-label` or `aria-labelledby` attribute.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

### Disabled

When a web application limits access to a resource, such as when the resource isn't available on the user's plan or a setup process first needs to complete, a link to the resource may need to be disabled.

The native `<a>` element doesn't support the `disabled` attribute, so the recommended method to disable it is to remove its `href` attribute, which not only removes its ability to navigate but also removes its `link` role, its tab stop, and its need for a `disabled` or an `aria-disabled` attribute. You can disable a custom link the same way: disable its navigation in code and remove its `link` role and tab stop.

But when users need to be aware of a resource that *could* be available, its link may retain its `link` role, with or without its place in the tab order. In this case, the link must be inoperable and carry `aria-disabled="true"`.

To disable a native `<a>` element without losing its role, remove its `href` attribute and set `role="link"` and `aria-disabled="true"`. To keep its tab stop as well, add `tabindex="0"`. With no `href`, the link can't navigate, and browsers don't offer link operations such as copying its address or opening it in a new tab.

```html
<!-- Disabled link that keeps its role -->
<a
    role="link"
    aria-disabled="true">
    Annual report
</a>


<!-- Disabled link that keeps its role and its tab stop -->
<a
    role="link"
    tabindex="0"
    aria-disabled="true"
    aria-describedby="report-note">
    Annual report
</a>
<p id="report-note">
    Reports are available on the Pro plan.
</p>
```

Don't set `href="#"` or `href=""`, which can cause a page refresh and move focus. Don't set `href="javascript:void(0)"` either: it keeps link operations that lead nowhere useful, and a Content Security Policy that blocks inline script can block it.

A similar approach works with a custom link. Disable its navigation in JavaScript and set `aria-disabled="true"`.

Whenever a disabled link keeps its role, show visible text telling users why its resource isn't available, and reference that text from the link with `aria-describedby`.

**Avoids conflicting disabled states**

**Reported as:** Conflicting disabled values

A link must declare its disabled state one way only: with `aria-disabled`, never with `disabled` or both. In the rare case of a `<button>` element with `role="link"`, the native `disabled` attribute declares the state instead.

A link ignores the `disabled` attribute. When a link carries it alongside `aria-disabled`, the two can disagree, and assistive technology reports whatever `aria-disabled` says, whatever the code meant. When a `<button>` with `role="link"` carries `aria-disabled` instead of `disabled`, it stays operable and in the tab order while assistive technology reports it as disabled. Either way, screen reader users are told the wrong thing about whether the link works.

The recommended method is to remove the `href` attribute from an `<a>` element when its resource isn't available, which removes its `link` role, its tab stop, and its function.

A link that keeps its role while it's disabled sets `aria-disabled="true"` alone, and removes it or sets it to `false` when it's enabled again. A `<button>` with `role="link"` uses `disabled` alone.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Link uses aria-disabled rather than disabled**

**Reported as:** Element does not support the disabled attribute

A link must convey its disabled state with `aria-disabled`, not the `disabled` attribute.

The `<a>` element doesn't support `disabled`, nor do most elements that can accept the `link` role, so browsers ignore it. When a link carries `disabled`, assistive technology still reports an available link, even when its event listeners are removed and it's out of the tab order. Screen reader users then try to follow a link that is meant to be unavailable.

Remove `href` from an `<a>` element to disable it. For a link that keeps its role, set `aria-disabled="true"`. On an `<a>` element, also remove `href` and set `role="link"`. On a custom link, block activation in its event handlers.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Disables only when role allows**

**Reported as:** Component does not support disabled state

A link's disabled state must sit on an element with the `link` role, not on an element whose role can't be disabled.

When `href` is removed from an `<a>` element and `aria-disabled="true"` is added without `role="link"`, the element has no role, and the state has nowhere to go. The same happens when `aria-disabled` is set on a wrapper around the link, such as a list item. Screen reader users hear plain text, or a link that still seems available, rather than a link they can't use.

Set `aria-disabled="true"` on the link itself. On an `<a>` element without `href`, set `role="link"` along with it, as the examples above do.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

**Disables only elements that support it**

**Reported as:** Element type does not support disabled state

An element in a link must carry `disabled` or `aria-disabled` only when its role supports a disabled state.

When the state sits on an element whose role has none, such as a wrapper, a list item or a heading, assistive technology may drop it or report it on something users can't operate, while the control that really is unavailable is still reported as available.

Remove the attribute from that element, and set the disabled state on the control itself, using an element or role that supports it, such as a native `<button>`.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

### Forbidden interactive children

A link contains no other interactive elements. HTML is explicit about this for the native element: no descendant of an `<a>` may be interactive content or another `<a>`, or carry a `tabindex` attribute. Nesting one control inside another leaves it ambiguous which of them a click or a key press reaches, and browsers and assistive technologies resolve that ambiguity differently.

**Link has no interactive children**

**Reported as:** Forbidden interactive children; Nested interactive elements

A link must not contain another interactive element, such as a button or a second link.

When one control is nested inside another, neither the browser nor assistive technology has a reliable way to present both. Nesting an `<a>` inside another `<a>` is invalid HTML, and the parser lifts the inner anchor out of the outer one, so the structure that renders isn't the structure you wrote.

When the nesting does survive, some assistive technologies report only the outer control and some report both, so screen reader users hear a different number of controls depending on what they use, and a click or a key press has two plausible targets with only one of them acting.

Take the inner control out. When both actions are needed, restructure them as siblings, each with its own role, accessible name, and activation behavior, so each has its own place in the tab order.

**Severity:** Serious

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [4.1.2 Name, Role, Value](https://www.w3.org/TR/WCAG22/#name-role-value) (A) | For all user interface components, the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to assistive technologies. |
| EN 301 549 | [9.4.1.2 Name, Role, Value](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(d)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | Sufficient information about a user interface element including the identity, operation and state of the element shall be available to assistive technology. When an image represents a program element, the information conveyed by the image must also be available in text. |

## Relationships

A link may contain complex, non-interactive content, but it's not a composite widget.

A link's primary function is navigating to its resource, but it can also open a context menu with a right-click, Control-click, or a specified keyboard action other than Enter. When it does, set `aria-controls` to the ID of the menu and dynamically set `aria-expanded` to indicate when the menu is displayed.

If the context menu opens in a popup, also add `aria-haspopup` with the appropriate value.

When the link's resource is the current resource, as may happen when the link is in a list of internal navigation links, set `aria-current="page"`.

### aria-owns

A link holds its text and any icon inside the anchor, where the DOM already makes them part of the link, so a link has no need for `aria-owns`.

**Avoids aria-owns**

**Reported as:** Avoid aria-owns

**General check.** Evinced checks that the link doesn't use `aria-owns` to claim elements elsewhere in the document as its children. This check runs on every UI pattern, not only on links.

A link should not use `aria-owns`.

When `aria-owns` lists text or an icon that's already inside the anchor, the attribute and the markup record the same structure twice and agree only until one of them changes. When the markup is edited and the attribute isn't, the attribute wins in the accessibility tree, and the link's name can stop matching its visible text.

Remove `aria-owns` from the link and let the anchor's content state its structure. When the link opens a context menu, reference the menu with `aria-controls` instead.

## Operation

With a pointer, clicking or tapping a link follows it. With a keyboard, the Tab key moves focus to the link and the Enter key follows it. Unlike a button, a link is not activated with the Space key. Space scrolls the page, and a custom link should leave it that way. Shift + F10 optionally opens a context menu for the link, which browsers provide for a native anchor.

An `<a>` element with an `href` attribute provides all of that, along with the browser behaviors users expect from a link, such as opening in a new tab, copying the destination, and showing the target on hover or focus.

Duplicating all the behavior of the native anchor element in a custom link is difficult. Whether the custom link uses the `window.location` API or the new Navigation API, it doesn't duplicate the behavior of `<a href="url">`.

A custom link usually does not:

-   Have native Control-click, Command-click, or Shift-click behavior
-   Replicate the native anchor attributes `target`, `download`, `ping`, `rel`, or `referrerpolicy`
-   Display the destination on hover
-   Support CSS styling with `:visited`
-   Enable copying or sharing the link destination
-   Become disabled by removing an attribute (removing `href` disables an anchor, `<a>`)

### Focus sequence

A link is in the tab order when its resource is available.

An `<a>` element with an `href` attribute is focusable on its own. A custom link needs a `tabindex="0"` attribute. Either way, the tab stop belongs on the same element that carries the `link` role and the accessible name, so that what users land on is what assistive technology describes.

**Link is in the tab order**

**Reported as:** Keyboard accessible

A link must be reachable with the Tab key.

When a link is built from an element that isn't natively focusable, such as a `<span>` or `<div>`, keyboard users can't reach it unless it explicitly sets `tabindex`. Even an anchor element, `<a>`, without an `href` isn't interactive and isn't in the tab order.

When it's necessary to base a custom link on a non-interactive element, add `tabindex="0"` to put it in the tab order. And don't set `tabindex` to a value greater than `0` to override its DOM-order position in the tab order.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [2.1.1 Keyboard](https://www.w3.org/TR/WCAG22/#keyboard) (A) | All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes, except where the underlying function requires input that depends on the path of the user's movement and not just the endpoints. |
| EN 301 549 | [9.2.1.1 Keyboard](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(a)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | When software is designed to run on a system that has a keyboard, product functions shall be executable from a keyboard where the function itself or the result of performing a function can be discerned textually. |
| 508 Trusted Tester | [2.1.1-keyboard-access, 4.A](https://section508coordinators.github.io/TrustedTester/keyboard.html#check-211-keyboard-access) | All functionality can be accessed and executed using only the keyboard. |

**Tab order skips disabled link**

**Reported as:** Disabled element focusable

A link that presents as disabled should not be in the tab order.

When a link keeps its tab stop after it's been disabled, keyboard users land on something they can't use. The anchor element `<a>` can't lean on the `disabled` attribute to prevent this because it doesn't support it, nor do most elements that can accept the `link` role.

The recommended method is to remove the `href` attribute from an `<a>` element, which takes it out of the tab order along with its role. To keep the role without the tab stop, set `role="link"` and `aria-disabled="true"` on it. For a custom link, remove `tabindex="0"`.

Keeping a disabled link focusable is a recognized alternative when users need to find it and learn why it's unavailable. If you take that route, set `aria-disabled="true"`, make sure activating it does nothing (on an `<a>` element, remove `href` and set `role="link"` and `tabindex="0"`), and reference visible text giving the reason with `aria-describedby`.

**Severity:** Minor

This issue is classified as "**Best Practice**," meaning it isn't tied to a specific WCAG success criterion or any other regulation or standard; however it still affects the experience of some users. These issues fall outside formal compliance requirements, yet addressing them improves usability and accessibility in practice.

**Puts focus on element with link role**

**Reported as:** Focusable offset

A link must put focus on the element that carries the `link` role, not on a descendant inside it.

When focus lands on a child of the element with `role="link"`, the focused element exposes no `link` role to assistive technology, so users tabbing through the page aren't told they've reached a link even though they may be able to operate it.

Make the element with the role focusable, either by using an `<a>` element with an `href` attribute or by keeping both `tabindex="0"` and `role="link"` on the interactive element.

**Severity:** Minor

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [2.1.1 Keyboard](https://www.w3.org/TR/WCAG22/#keyboard) (A) | All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes, except where the underlying function requires input that depends on the path of the user's movement and not just the endpoints. |
| EN 301 549 | [9.2.1.1 Keyboard](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(a)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | When software is designed to run on a system that has a keyboard, product functions shall be executable from a keyboard where the function itself or the result of performing a function can be discerned textually. |
| 508 Trusted Tester | [2.1.1-keyboard-access, 4.A](https://section508coordinators.github.io/TrustedTester/keyboard.html#check-211-keyboard-access) | All functionality can be accessed and executed using only the keyboard. |

### Link activation

A link with an available resource navigates to it when the user clicks with a pointer or presses the Enter key. A link whose resource is not available does nothing.

A native anchor, `<a href="{resource}">`, needs no code to do that. A custom link needs both `click` and `keydown` event handlers. Best practice is for both listeners to run the same navigation code.

**Activates with the Enter key**

**Reported as:** Link cannot be activated with keyboard

A link must navigate to its destination when the user presses Enter.

When a custom link has only a `click` handler, keyboard users can't activate it. Users press Enter, get no error and no change, and conclude the link is broken.

Use an `<a>` element with an `href` attribute, which needs no code to activate with a pointer or the Enter key, or add both `click` and `keydown` listeners so that all users can use it.

**Severity:** Critical

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [2.1.1 Keyboard](https://www.w3.org/TR/WCAG22/#keyboard) (A) | All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes, except where the underlying function requires input that depends on the path of the user's movement and not just the endpoints. |
| EN 301 549 | [9.2.1.1 Keyboard](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |
| Section 508 | [1194.21(a)](https://www.federalregister.gov/documents/2018/01/18/2018-00712/section-508-standards-update#d21) | When software is designed to run on a system that has a keyboard, product functions shall be executable from a keyboard where the function itself or the result of performing a function can be discerned textually. |
| 508 Trusted Tester | [2.1.1-keyboard-access, 4.A](https://section508coordinators.github.io/TrustedTester/keyboard.html#check-211-keyboard-access) | All functionality can be accessed and executed using only the keyboard. |

**Link ignores activation when disabled**

**Reported as:** Disabled element active

A link that presents as disabled must not navigate when it's activated.

When a link carries `aria-disabled="true"` or is styled to look unavailable but keeps its click and key handlers, users could still activate it, navigate somewhere unexpected, and lose their place on the page.

Remove `href` from an anchor element, `<a>`, to disable it, and set `role="link"` when it has to keep its role. For a custom link, have the event listeners check the disabled state and return before navigating.

**Severity:** Moderate

| Standard | Success Criterion | Reference |
| --- | --- | --- |
| WCAG 2.2 | [1.3.1 Info and Relationships](https://www.w3.org/TR/WCAG22/#info-and-relationships) (A) | Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. |
| EN 301 549 | [9.1.3.1 Info and Relationships](https://www.etsi.org/standards/etsi-301-549) | Same as the WCAG text. |

### Event listener type

When script in a link responds to keys, it listens for `keydown` or `keyup`. The `keypress` event is deprecated, and browsers don't fire it for many keys, including the arrow keys, Home, End and Escape.

**Avoids the keypress event**

**Reported as:** Deprecated keypress listener

A link's key handling should use `keydown` or `keyup`, not `keypress`.

When a handler listens for `keypress`, keys the browser doesn't send through that event go unanswered, and keyboard users find the link ignoring keys it's meant to respond to.

Replace each `keypress` listener with a `keydown` listener, and read the key from `event.key`.

**Severity:** Minor

This issue is classified as "**Best Practice**," meaning it isn't tied to a specific WCAG success criterion or any other regulation or standard; however it still affects the experience of some users. These issues fall outside formal compliance requirements, yet addressing them improves usability and accessibility in practice.

## FAQ

**Which WCAG success criteria do the link issues relate to?**

Most relate to 4.1.2 Name, Role, Value: the link's role, its accessible name, how it conveys a disabled state, and keeping other interactive elements out of it. Reaching the link with the Tab key, putting focus on the element with the role, and following it with Enter relate to 2.1.1 Keyboard. A disabled link that still navigates relates to 1.3.1 Info and Relationships.

Taking a disabled link out of the tab order maps to no WCAG success criterion and is a best practice.

**Why are some link issues marked as Critical and others as Minor?**

Severity reflects how much an issue gets in users' way. Critical issues stop users outright: a link with no role, one keyboard users can't reach, or one Enter doesn't follow. Serious issues leave a link unnamed, misreport a disabled state, or nest controls so users can't tell what they'll operate. A disabled link that still navigates is Moderate. A disabled link left in the tab order, or focus that lands inside the link rather than on it, is Minor.

The `aria-owns` check and the check on where the role sits carry no severity: Evinced reports them as a general check and a sanity check.

## Related Patterns

-   [Button](https://knowledge.evinced.com/web/ui-patterns/button): performs an action on the current page rather than navigating

## Recommended Reading

-   [Link Pattern | W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/link/)
-   [link role | W3C WAI-ARIA](https://www.w3.org/TR/wai-aria-1.3/#link)
-   [Understanding Success Criterion 2.4.4: Link Purpose (In Context) | W3C WAI](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html)
-   [`<a>`: The Anchor element | MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a)
-   [ARIA: link role | MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/link_role)
