Visibility of the keyboard focus

Make sure a keyboard user can clearly see where the focus is while navigating through a web page. Without a visible focus indication, it is very easy for a sighted user to get lost and abandon the page.

There are two ways to show an interactive HTML element has keyboard focus:

  • keep the default outline added by the browser intact;
  • design your own focus indicator.

Keep the outline of the browser intact

Most modern browsers have strong default :focus styling, making it easy for a user to tab from control to control and see clearly where they are on the page. The advantage of keeping that outline is that you don’t have to do anything. The browser handles it all.

This also passes WCAG Success criterion 2.4.7 Focus Visible, as explained in Technique G149: Using user interface components that are highlighted by the user agent when they receive focus.

The disadvantage of using the native outline is that each browser displays the outline differently, and that outline may be hard to see with your design.

Design your own focus indicator

A more reliable way to add a focus indicator is by designing your own. Then the visual representation is consistent and independent of the browser. This also gives you the opportunity to design the outline differently for dark and light mode.

When you use a custom design, the color contrast criteria of WCAG apply. The color contrast the focus outline or border color should have a contrast ratio of at least 3:1. The contrast should apply against the background, and also against the background color of the focusable element itself. For example, for a button or input field that has a custom background color.

Provide an outline or border with:

  • a thickness of at least 2 CSS pixels;
  • a color contrast ratio of at least 3:1 against adjacent colors;
  • a color contrast ratio of at least 3:1 between the same pixels in the focused and unfocused states.

The topic Styling hover and focus, in the section Design and user experience of this documentation, also addresses the design guidelines of keyboard focus and mouse hover.

CSS :focus-visible

:focus-visible is a CSS pseudo-class that only applies focus styles when users navigate with the keyboard. Mouse users won’t see a focus outline when they click on an element. Read more in MDN: focus-visible.

button:focus-visible {
    outline: 2px solid #757575;
}

How to test for visual focus

Tab through your pages and check if the keyboard focus is visible. If the visual focus indicator is created with custom CSS, check the color contrast. The color contrast the focus outline or border color should have a contrast ratio of at least 3:1. Against the background, but also against the background color of the focusable element itself.

How to test with a keyboard is described with Keyboard navigation testing in this documentation.

Examples

Don’t: remove the outline without adding custom styling.

button {
 outline: 0;
}

Do: add custom styling when you remove the default outline.

button {
 outline: 0;
}

button:focus-visible {
    border: 2px solid #757575;
}

Resources

WCAG Success Criteria for visual focus

Other resources