wicg-focus-ring v3.0.2

Based on the proposed CSS :focus-ring pseudo-selector, this prototype adds a focus-ring class to the focused element, in situations in which the :focus-ring pseudo-selector should match.

Details

• Read the Explainer.
• Read the Spec.
• Try the Demo.

Polyfill

Installation

npm install --save wicg-focus-ring

We recommend only using versions of the polyfill that have been published to npm, rather than cloning the repo and using the source directly. This helps ensure the version you're using is stable and thoroughly tested.

If you do want to build from source, make sure you clone the latest tag!

Usage

1. Add the script to your page

    ...
    <script src="/node_modules/wicg-focus-ring/dist/focus-ring.js"></script>
  </body>
</html>

2. Update your CSS

We suggest that users selectively disable the default focus style by selecting for the case when the polyfill is loaded and .focus-ring is not applied to the element:

/*
  This will hide the focus indicator if the element receives focus via the mouse,
  but it will still show up on keyboard focus.
*/
.js-focus-ring :focus:not(.focus-ring) {
  outline: 0;
}

If there are elements which should always have a focus ring shown, authors may explicitly add the focus-ring class. If explicitly added, it will not be removed on blur.

How it works

The script uses two heuristics to determine whether the keyboard is being used:

• a focus event immediately following a keydown event where the key pressed was either Tab, Shift + Tab, or an arrow key.
• focus moves into an element which requires keyboard interaction, such as a text field
• TODO: ideally, we also trigger keyboard modality following a keyboard event which activates an element or causes a mutation; this still needs to be implemented.

Dependencies

The :focus-ring polyfill uses the Element.classList API which is not supported in IE 8-9. In accordance with the W3C's new Polyfill guidance, the :focus-ring polyfill does not bundle other polyfills. If you need to support these older browsers you should add the classList polyfill to your page before loading the :focus-ring polyfill. Using a service like Polyfill.io will handle feature detecting and loading the necessary polyfills for you.