useFocusRing

Determines whether a focus ring should be shown to indicate keyboard focus. Focus rings are visible only when the user is interacting with a keyboard, not with a mouse, touch, or other input methods.

installyarn add react-aria
version3.19.0
usageimport {useFocusRing} from 'react-aria'
View repository
GitHub
View package
NPM

API#

useFocusRing( (props: AriaFocusRingProps )): FocusRingAria

Introduction#

The useFocusRing hook returns whether a focus ring should be displayed to indicate keyboard focus for a component. This helps keyboard users determine which element on a page or in an application has keyboard focus as they navigate around. Focus rings are only visible when interacting with a keyboard so as not to distract mouse and touch screen users.

If CSS classes are being used for styling, see the FocusRing component for a shortcut.

Options#

NameTypeDefaultDescription
withinboolean'false'

Whether to show the focus ring when something inside the container element has focus (true), or only if the container itself has focus (false).

isTextInputboolean—Whether the element is a text input.
autoFocusboolean—Whether the element will be auto focused.

Result#

NameTypeDescription
isFocusedbooleanWhether the element is currently focused.
isFocusVisiblebooleanWhether keyboard focus should be visible.
focusPropsDOMAttributesProps to apply to the container element with the focus ring.

Example#

This example shows how to use useFocusRing to adjust styling when keyboard focus is on a button. Specifically, the outline property is used to create the focus ring when isFocusVisible is true.

See useCheckbox, useRadioGroup, and useSwitch for more advanced examples of focus rings with other styling techniques.

import {useFocusRing} from 'react-aria';

function Example() {
  let { isFocusVisible, focusProps } = useFocusRing();

  return (
    <button
      {...focusProps}
      style={{
        WebkitAppearance: 'none',
        appearance: 'none',
        background: 'green',
        border: 'none',
        color: 'white',
        fontSize: 14,
        padding: '4px 8px',
        outline: isFocusVisible ? '2px solid dodgerblue' : 'none',
        outlineOffset: 2
      }}
    >
      Test
    </button>
  );
}

import {useFocusRing} from 'react-aria';

function Example() {
  let { isFocusVisible, focusProps } = useFocusRing();

  return (
    <button
      {...focusProps}
      style={{
        WebkitAppearance: 'none',
        appearance: 'none',
        background: 'green',
        border: 'none',
        color: 'white',
        fontSize: 14,
        padding: '4px 8px',
        outline: isFocusVisible
          ? '2px solid dodgerblue'
          : 'none',
        outlineOffset: 2
      }}
    >
      Test
    </button>
  );
}

import {useFocusRing} from 'react-aria';

function Example() {
  let {
    isFocusVisible,
    focusProps
  } = useFocusRing();

  return (
    <button
      {...focusProps}
      style={{
        WebkitAppearance:
          'none',
        appearance:
          'none',
        background:
          'green',
        border: 'none',
        color: 'white',
        fontSize: 14,
        padding:
          '4px 8px',
        outline:
          isFocusVisible
            ? '2px solid dodgerblue'
            : 'none',
        outlineOffset: 2
      }}
    >
      Test
    </button>
  );
}