Learn Focus ring visibility

Unpoly lets you control whether a focused fragment shows a visible focus ring. Elements focused by Unpoly get a CSS class that says whether a ring is wanted, so your stylesheet can show rings for keyboard users and hide them for mouse and touch users.

Because Unpoly often focuses new content, you may see focus outlines 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 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 sets an .up-focus-visible class.
• If the user interacted via mouse, touch or stylus, Unpoly sets an .up-focus-hidden class instead.

<main class="up-focus-hidden" tabindex="-1"> <!-- mark: class="up-focus-hidden" -->
  Content focused after a mouse click
</main>

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 tries to force or unset :focus-visible whenever it sets a visibility class, 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 the 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 a 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 gets an .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 following configuration keeps the default strategy, but never shows a focus ring on a main fragment:

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, set an [up-focus-visible] attribute on any link or form:

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

When rendering from JavaScript, pass a { focusVisible } option:

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

The same option is accepted by up.focus().