Step by Step

Focus visible: how to style the focus indicator in CSS

8 min read
Mikhail ShaymardanovWeb Quality and Accessibility Expert

When a design team strips the outline from clicked buttons, sighted keyboard users lose track of where they are. That outline is the focus indicator: it shows which element will get the next key press. With :focus-visible, you hide it on mouse click and keep it for the keyboard. Below you'll find a style that stays readable on any solid background, and how to test it.

One focus style, from CSS to testing


#What the keyboard focus indicator is for?

The focus indicator shows on screen which element the next key press will reach. That element has the focus: the link that Enter will open, the field where your typing appears. Most of the time the indicator is an outline, as on the website of Balance Wheel Watch Repair, a shop we'll follow all the way to the test.

Screenshot: the Balance Wheel Watch Repair menu, with the Pricing link outlined in blue.Marker 1. The Pricing link in the menu, with the blue focus outline around it.
After three presses of Tab, only the 2 px blue outline around Pricingmarker 1 shows where keyboard focus is.

Without that outline, a sighted person using the keyboard can't tell where they are. It helps:

  • people who can't use a mouse or need to avoid one, because of a motor disability, repetitive strain pain or an arm in a cast;
  • people who control the computer by voice, with an on-screen keyboard or with a switch (an adapted button), since these tools act like a keyboard;
  • people with low vision who zoom in and only see part of the screen at a time;
  • people with attention or memory difficulties, who need to find their place again.

Blind people use the keyboard as well, but a screen reader guides them by reading the page aloud. The outline is first of all for people who can see the screen.

For years, browsers drew this outline on almost anything that received focus, even a clicked button. Many people found it ugly, and plenty of sites removed it, and everyone on that list lost the one cue they relied on.

Browsers now show their outline only when it helps, mostly for the keyboard. In 2020, Chrome also replaced its light outline with a dark ring edged with a thin white line, so it stands out on both light and dark backgrounds.

#Which rules require a visible focus?

WCAG, the web accessibility guidelines, requires a visible focus in its Focus Visible criterion, at level AA. The criterion dates back to the first version of WCAG 2, so every version that US law points to includes it. Federal agencies follow Section 508, built on WCAG 2.0. State and local governments follow the ADA Title II rule, built on the next version. In Europe, the European Accessibility Act sets the goals and EN 301 549, the standard that turns them into testable requirements, repeats Focus Visible for web pages.


#How to remove the focus outline on click and keep it for the keyboard?

Put your focus style on :focus-visible, the selector that makes this distinction. The :focus selector applies every time an element gets focus, mouse clicks included. :focus-visible applies only when the browser decides focus is worth showing: during keyboard navigation, and always in fields where people type text.

When a script moves focus, as after a route change in a React app, the new element usually shows the ring only if the previous one did. A third selector, :focus-within, matches an element when it or something inside it has focus, such as a card whose link is focused.

Browsers already use :focus-visible for their own default style, so a clicked button normally shows no ring at all. If your designer sees one on click, look first for a :focus rule in the site's CSS or in a component library. On a text input, the ring on click is intended: people need to see where they are typing.

Screenshot: the Book a repair button twice, side by side. On the left, clicked, it has no ring; on the right, reached with Tab, a very dark blue outline surrounds it.
The Book a repair button, styled on :focus-visible: clicked with the mouse on the left, it has no ring; reached with Tab on the right, it gets a very dark blue outline.

#Why outline: none on :focus fails WCAG?

Many sites did the opposite, with an outline: none rule on :focus that removes the ring for everyone, keyboard users included. When no other indicator replaces it, the W3C, which publishes WCAG, lists this rule among the failures of Focus Visible. Delete those rules.

Avoid

Screenshot: the Book a repair button has keyboard focus, with no indicator at all.Marker 1. The Book a repair button, with no focus outline.
*:focus {
  outline: none;
}

Correct

Screenshot: the same button, surrounded by a very dark blue outline.Marker 1. The Book a repair button, with the very dark blue focus outline around it.
:focus-visible {
  outline: 2px solid #193146;
  outline-offset: 2px;
}
The Book a repair buttonmarker 1 has keyboard focus in both shots: with outline: none on :focus, nothing shows it; with the style on :focus-visible, a very dark blue outline surrounds it.

Why. The browser already decides when to show the ring, and your CSS only has to decide what it looks like.

That makes the old :focus:not(:focus-visible) trick and the focus-visible npm polyfill unnecessary. The selector has worked in every major browser since March 2022, and the polyfill is no longer maintained.


#Which focus ring style works across the whole site?

Draw the indicator with outline on :focus-visible, and keep its colors in CSS custom properties. An outline takes up no space, so nothing shifts when it appears, and it follows the rounded corners set by border-radius.

The higher the contrast between two colors, the easier they are to tell apart. An indicator drawn around the element needs at least 3:1 against the background the element sits on, as WCAG requires. Measure each background with the color contrast checker.

A site with backgrounds in several colors runs into a problem: one indicator color may not contrast with all of them, and with one color per area, some components always get missed. That is why a W3C technique draws the indicator in two colors. If the two reach 9:1 against each other, one of them reaches 3:1 on any solid background. The guarantee holds for an indicator drawn around the element on a single-color background; on a photo or a gradient, measure.

#The two-color focus ring on the demo site

Balance Wheel Watch Repair fits this case. Its page is white, and its navy footer, #0F172A, holds the newsletter form. Its current focus style, a 2 px blue #005FCC outline, reaches 5.98:1 on the white page and passes. In the footer it drops to 2.98:1 and fails, because WCAG never rounds a ratio up.

The W3C pair, near-white #F9F9F9 and very dark blue #193146, gives 12.71:1 between its two colors, above the 9:1 it needs. On the white page, the dark band carries the contrast at 13.38:1. In the footer, the light band takes over at 16.96:1.

Screenshot: the Book a repair and Sign up buttons of Balance Wheel Watch Repair with focus, before the fix at the top and after the fix at the bottom. At the top, the blue outline stands out clearly on the white page and less on the navy footer. At the bottom, the two-color outline stands out on both backgrounds. Contrast values are in the text above.
At the top, before the fix, the blue #005FCC outline drops to 2.98:1 on the navy footer; at the bottom, after the fix, the light band of the two-color outline reaches 16.96:1 there.

The style to copy:

:root {
  --focus-light: #F9F9F9;
  --focus-dark: #193146;
}
 
:focus-visible {
  outline: 2px solid var(--focus-light);
  outline-offset: 0;
  box-shadow: 0 0 0 4px var(--focus-dark);
}

Why. The outline draws the light band against the element, and the shadow draws the dark band around it: each band is 2 px wide.

#Getting the focus state into the design

On its own, each 2 px band is also large enough for Focus Appearance (2.4.13), the strictest level, AAA. Aim for it from the first mockup, so the team only designs focus once.

To keep design from removing it again, get the focus state into the mockups. Spec both colors for every interactive element: a 2 px light band #F9F9F9 against the element and a 2 px dark band #193146 around it.


#Why a box-shadow focus ring disappears in Windows high contrast mode?

When Windows high contrast is on, a focus style drawn with a shadow alone disappears, because the browser removes every box-shadow. This setting is one case of forced colors mode, where the browser replaces the page's colors with a few colors the user picked. An outline stays visible in one of the theme's colors, which is why the style above draws its light band with outline.

Screenshot: two focus styles on a button, in normal colors on the left and in forced colors on the right. At the top, the shadow-only style disappears in forced colors; at the bottom, the outline stays.
Normal colors on the left, forced colors in Chrome on the right: the box-shadow-only focus at the top disappears, while the one that keeps an outline, at the bottom, stays visible.

If a component has to keep a shadow-only focus, add outline: 2px solid transparent to its focus style. That outline stays invisible in normal colors and shows up in forced colors. Also avoid adding a border on focus: it takes up space, so the content shifts every time.

#Tailwind ring and outline-none in forced colors

In Tailwind, the ring class produces a box-shadow, so it disappears in forced colors. Version 4 also changed what one class means. In v3, outline-none set a transparent outline, which forced colors made visible. In v4, that transparent outline is called outline-hidden, and outline-none removes the outline entirely.

A project upgraded to v4 by hand that keeps focus:outline-none therefore loses its focus indicator in forced colors. Pair every ring with outline-hidden, or switch to the outline classes.

In forced colors, any box-shadow focus disappears; an outline shows up, even a transparent one, except Tailwind v4 outline-none.
Focus styleIn forced colors
outlineStays visible, in a theme color
box-shadow aloneDisappears
Tailwind ringDisappears, like any box-shadow
box-shadow with outline: 2px solid transparentThe outline shows, in a theme color
outline-hidden (Tailwind v4)The outline shows
outline-none (Tailwind v4)No indicator left

#How to test focus visible with the keyboard?

On each page template, go down the tab order with Tab to the footer, then back up with Shift+Tab. Every element should show the indicator. Focus Not Obscured (2.4.11) also asks that none of them end up fully hidden under a sticky header, one that stays pinned to the top of the screen.

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

On the watch repair site, Tab goes all the way to Sign up and Shift+Tab comes back: the two-color focus ring shows on the white and the navy backgrounds alike.

Then switch to the mouse. Clicking a button should show no ring, while clicking into a text input shows it.

To simulate forced colors in Chrome, open DevTools, then the Rendering panel. Pick forced-colors: active and run through the page again. If the site has a dark theme, repeat with prefers-color-scheme: dark.

On a Mac, Safari needs two settings, because by default Tab only stops on form fields and pop-up menus there. In Safari's Advanced settings, turn on the option for Tab to highlight each item, then turn on keyboard navigation in the Keyboard section of macOS System Settings. Safari also doesn't give focus to a clicked button, so no ring shows on click there, whatever the CSS says.

Before you ship, check:

Focus can also land on a transparent element: on a product page of the Shopify Horizon theme demo, which Lighthouse scores 95, the eighth press of Tab reaches an invisible button.

Our guide to the new criteria of WCAG 2.2 shows the CSS fix for a sticky header that hides focus.

RGAA 5: get compliant before the new version is released
Share this article

Frequently asked questions

WCAG doesn't require it: it asks for at least one mode of operation where focus is visible, and keyboard navigation counts as one. The W3C still suggests thinking about it, since a visible focus can help mouse users too.

The right call depends on your audience. A ring that shows up only some of the time can confuse people who aren't comfortable with computers. On a service built for them, put the style on :focus. In Chrome, anyone can also turn it on for the mouse with the accessibility setting "Show a quick highlight on the focused object".

No. A gap between the element and its outline is allowed, and it can make the indicator easier to see. In CSS, you set that gap with outline-offset.

The outline follows the rounded corners set by border-radius. On a link that wraps onto two lines, browsers draw it either around each piece or as one shape. The W3C accepts the separate pieces for Focus Appearance.

Focus Visible, at level AA, only asks that the focus indicator be visible. Non-text Contrast (1.4.11), also level AA, asks for 3:1 between an indicator the site draws and the colors around it.

Focus Appearance is a level AAA criterion. It asks for an indicator at least as large as a 2 px line all around the element, and those pixels must change color with 3:1 between the unfocused and focused states. The first two decide whether the site conforms. Focus Appearance works best as a target for the design.

Pass the focusVisible option to the focus() method: element.focus({ focusVisible: true }) shows the indicator, and false keeps it hidden. Firefox supports it since version 104, Safari since 18.4 and Chrome since 145.

Without the option, each browser follows its own rules. Most of the time, the new element copies the one that had focus before it, so it shows the indicator after a key press and hides it after a click on a button.

Keep some visible sign of focus. In one of its examples, the W3C treats the blinking text cursor in a field as enough. France's RGAA asks for more: the outline or the background has to change, with at least 3:1 contrast.

If the design removes the outline from an input, replace it with a border or background that changes on focus and meets that 3:1 threshold.