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#

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 addWindowFocusTracking which can attach our event listeners inside the iframe. You should call this function with an element inside the window you wish to add. We'll retrieve the relevant elements based on that. Note, you do not need to call this for the 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.