useFocusVisible

Manages focus visible state for the page, and subscribes individual components for updates.

API#

Features#

useFocusVisible handles focus interactions for the page and determines whether keyboard focus should be visible (e.g. with a focus ring). Focus visibility is computed based on the current interaction mode of the user. When the user interacts via a mouse or touch, then focus is not visible. When the user interacts via a keyboard or screen reader, then focus is visible. This is similar to the :focus-visible pseudo class in CSS.

To determine whether a focus ring should be visible for an individual component rather than globally, see useFocusRing.

Example#

This example shows focus visible state and updates as you interact with the page. By default, when the page loads, it is true. If you press anywhere on the page with a mouse or touch, then focus visible state is set to false. If you keyboard navigate around the page then it is set to true again.

Note that this example uses the isTextInput option so that only certain navigation keys cause focus visible state to appear. This prevents focus visible state from appearing when typing text in a text field.

import {useFocusVisible} from 'react-aria';

function Example() {
  let { isFocusVisible } = useFocusVisible({ isTextInput: true });

  return (
    <>
      <div>Focus visible: {String(isFocusVisible)}</div>
      <label style={{ display: 'block' }}>
        First Name: <input />
      </label>
      <label style={{ display: 'block' }}>
        Last Name: <input />
      </label>
    </>
  );
}

import {useFocusVisible} from 'react-aria';

function Example() {
  let { isFocusVisible } = useFocusVisible({
    isTextInput: true
  });

  return (
    <>
      <div>Focus visible: {String(isFocusVisible)}</div>
      <label style={{ display: 'block' }}>
        First Name: <input />
      </label>
      <label style={{ display: 'block' }}>
        Last Name: <input />
      </label>
    </>
  );
}

import {useFocusVisible} from 'react-aria';

function Example() {
  let {
    isFocusVisible
  } = useFocusVisible({
    isTextInput: true
  });

  return (
    <>
      <div>
        Focus visible:
        {' '}
        {String(
          isFocusVisible
        )}
      </div>
      <label
        style={{
          display:
            'block'
        }}
      >
        First Name:{' '}
        <input />
      </label>
      <label
        style={{
          display:
            'block'
        }}
      >
        Last Name:{' '}
        <input />
      </label>
    </>
  );
}

Advanced#

Adds a window (ie iframe) to the list of windows that are being tracked for focus visible.

Sometimes apps render portions of their tree into an iframe. In this case, we cannot accurately track if the focus is visible because we cannot see interactions inside the iframe. If you have this in your application's architecture then we have a function which can attach our event listeners inside the iframe, addWindowFocusTracking. Note, this is not needed for your default window, as we call it for you.

When you are ready to stop listening, but you do not wish to unmount the iframe, you may call the cleanup function returned by addWindowFocusTracking. Otherwise, when you unmount the iframe, all listeners and state will be cleaned up automatically for you.