API Focus ring visibility

Unpoly lets you control whether a focused fragment shows a visible focus ring.

Because Unpoly often focuses new content, you may see focus outline appear in unexpected places. Try to resist an initial instinct to just remove focus rings globally using CSS. Focus rings are important for users of keyboards and screen readers to be able to orient themselves as the focus moves on the page. However, mouse and touch users often dislike the visual effect of a focus ring.

Visibility classes

To help your CSS show or hide focus rings in the right situation, Unpoly assigns CSS classes to the elements it focuses:

• If the user interacted with the keyboard or if the focused element is a form field, Unpoly will set an .up-focus-visible class.
• If the user interacted with via mouse, touch or stylus, Unpoly will set an .up-focus-hidden class instead.

Note

The web platform uses the :focus-visible pseudo-class to indicate focus ring visibility. However browsers often incorrectly apply :focus-visible during script-driven navigations like Unpoly.

Unpoly will try to force :focus-visible whenever it sets .up-focus-visible, but can only do so in some browsers.

Hiding unwanted focus rings with CSS

You may see unwanted focus rings that you inherited from a user agent stylesheet or from a CSS framework like Bootstrap. You can remove these outlines for most mouse and touch interactions, using CSS like this:

:focus:not(:focus-visible, .up-focus-visible),
.up-focus-hidden {
  outline: none !important;
}

By default Unpoly removes an outline CSS property from elements with an .up-focus-hidden class.

Tip

CSS frameworks might render focus rings using properties other than outline. For example, Bootstrap uses a box-shadow to produce a blurred outline.

Styling focus rings on new component

When creating a new interactive component, you should make it focusable using the keyboard's Tab key by assigning a [tabindex] attribute:

<span class="my-button" tabindex="0">
  ...
</span>

To show a focus ring for keyboard users only, use CSS like this:

.my-button {
  &:focus-visible:not(.up-focus-hidden),
  &.up-focus-visible {
    outline: 1px solid royalblue;
  }
}

Customizing focus ring visibility

Instead of hiding unwanted focus rings with CSS, you can configure the up.viewport.config.autoFocusVisible function. This function decides whether a given element should get a .up-focus-visible or .up-focus-hidden class.

The default strategy is implemented like this:

up.viewport.config.autoFocusVisible = ({ element, inputDevice }) =>
  inputDevice === 'key' || up.form.isField(element)

See up.event.inputDevice for a list of values for the { inputDevice } property.

You can replace or extend the default strategy. For example, the configuration would generally use the default strategy, but never show a focus ring on main elements:

let defaultVisible = up.viewport.config.autoFocusVisible
up.viewport.config.autoFocusVisible = (options) =>
  defaultVisible(options) && !up.fragment.matches(options.element, ':main')

Overriding visibility for a single interaction

If you are happy with your default strategy, but want to override it for a single interaction, you can set an [up-focus-visible] attribute on any link or form:

<a href="/path" up-focus=":main" up-focus-visible="false">Click me</a> <!-- mark: up-focus-visible="false" -->

When rendering from JavaScript, you can pass an { focusVisible } option:

up.navigate({
  url: '/path',
  focus: ':main', 
  focusVisible: false // mark: focusVisible: false
})