OnlineNexusAccess accessibility home Free scan

How to fix a missing keyboard focus outline in Shopify and WooCommerce themes

Press the Tab key on your store's homepage. Can you see where you are? If nothing seems to happen, or the highlight disappears on some buttons, your theme has probably removed the browser's focus outline. For people who shop with a keyboard, switch devices or voice control, that outline is the mouse pointer. This guide shows how to find the problem and add a clear focus style with a few lines of CSS.

Why the focus outline matters

WCAG success criterion 2.4.7 requires that any keyboard-operable interface has a visible focus indicator (Understanding Success Criterion 2.4.7: Focus Visible (W3C WAI)). The browser draws one by default, but many themes remove it with CSS like outline: none because designers find it untidy when clicking with a mouse. Without it, a keyboard user pressing Tab can't tell which link or button is active, so they can't reliably shop.

Browsers solved the original design complaint with the :focus-visible selector, which applies a style only when the browser decides focus should be visible, typically during keyboard navigation and not on a mouse click (:focus-visible (MDN Web Docs)). That means you can have a strong focus style for keyboard users without changing what mouse users see.

Step 1: Test your store

  1. Open your homepage, click in the address bar, then press Tab repeatedly.
  2. Watch the header links, search, cart, the main buttons, product cards and the footer. Each should show a clearly visible outline or highlight when it's focused.
  3. Repeat on a product page: variant options, quantity buttons and "Add to cart" are where problems usually hide.

The full routine is in our 10-minute keyboard test. Automated scanners, including ours, generally can't tell whether a focus indicator is visible, so this is one of the checks you have to do by hand.

Step 2: Find what removes the outline

Search your theme's CSS for outline: none, outline: 0 and outline-width: 0.

  • Shopify: in the theme code editor (Online Store > Themes > ... > Edit code), open the assets folder and search the main CSS files, for example base.css or theme.css.
  • WooCommerce: look in your theme's style.css and any CSS files it loads. Your browser's developer tools are faster: inspect a focused link and look for an outline rule with a line through it or set to none; the tools show the file and line.

You don't have to delete those rules. A more specific :focus-visible rule, added after them, brings the indicator back.

Step 3: Add a focus style

This short CSS gives every interactive element a clear two-colour ring that stays visible on both light and dark backgrounds. Change the two colours to match your brand, keeping strong contrast:

focus.css
/* Clear keyboard focus indicator (shows for keyboard users, not mouse clicks) */
a:focus-visible,
button:focus-visible,
input:focus-visible,
select:focus-visible,
textarea:focus-visible,
summary:focus-visible,
[tabindex]:focus-visible {
  outline: 3px solid #1a1aff !important;
  outline-offset: 2px !important;
  box-shadow: 0 0 0 5px #ffffff !important;
}

The outline is the main ring; the white box-shadow adds a halo so the ring is visible on dark buttons and images too. WCAG's non-text contrast criterion asks for at least a 3:1 contrast ratio for visual information needed to identify focus (Understanding Success Criterion 1.4.11: Non-text Contrast (W3C WAI)), and WCAG 2.2 adds more detailed guidance on focus appearance (Understanding Success Criterion 2.4.13: Focus Appearance (W3C WAI)). You can check your colours with our free contrast checker.

The !important flags are there because theme CSS sometimes removes outlines with very specific selectors. If your theme behaves without them, you can take them out.

Adding the CSS on Shopify

The easiest way is the theme editor: Online Store > Themes > Customize > Theme settings > Custom CSS, then paste and save (Add custom CSS (Shopify Help Center)). Shopify notes some limits: theme-wide custom CSS is limited to 1,500 characters, and the content property isn't available. The rule above fits comfortably.

If your theme is older and doesn't have a Custom CSS setting, add the rule at the very end of your main CSS file in the code editor instead, on a duplicate theme first (Duplicating themes (Shopify Help Center)). Theme updates may replace the file, so keep a copy of your change.

Adding the CSS on WooCommerce

Both of the first two options survive theme updates because WordPress stores the CSS separately from the theme files.

Check your own store in a minute or two. Our free scanner opens your homepage, a collection page, a product page and your cart in a real browser and lists the problems it can detect automatically, in plain English.

Run the free scan

Step 4: Check it everywhere

  • Tab through the homepage, a collection page, a product page and the cart again. Every stop should show the ring.
  • Check dark sections, sale banners and image buttons, where a single-colour outline can disappear.
  • Open the mobile menu and any pop-ups with the keyboard: focus should move inside them and stay visible.
  • Check app widgets (reviews, chat, pop-ups). They may use their own CSS; see our guide to app problems.

Sometimes the outline exists but disappears because focus has moved to something you can't see, such as a closed menu, a hidden cart drawer or an off-screen slide. Automated tools report some of these as "Hidden elements can still be reached by keyboard" (aria-hidden-focus); in our 10-store test sample this showed up on 2 stores. Fixing it usually means adding the hidden attribute or inert to closed menus and drawers in the theme's JavaScript, which is a job for whoever maintains your theme.

Common questions

Will this change how my store looks for mouse users?

In current browsers, generally not. :focus-visible lets the browser decide when to show the ring, and for mouse clicks on links and buttons it usually doesn't. Text fields are the exception: browsers normally show focus when you click into a field, because you need to know where you're typing.

Which colour should I use?

Pick a colour that contrasts at least 3:1 with every background it may appear on, or use the two-colour approach above (a dark ring with a light halo), which works on light and dark sections alike. Your brand's main button colour is often a good starting point if it is dark enough.

My theme already has a focus style but it is very faint. What then?

The same CSS works: because it's added later and uses !important, it overrides a faint theme style. If the theme uses a box-shadow instead of an outline for focus, you may see both at once; remove the box-shadow line from the rule above if it looks doubled.

Technical fixes, not legal advice. This guide explains website accessibility from a technical point of view. We are not a law firm, and nothing here is legal advice. No scan, fix or guide can guarantee legal compliance, the outcome of any demand letter or lawsuit, or protection from future claims. If you have received a legal claim, please consult a qualified attorney about it.

Sources