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.

install	`yarn add @react-aria/focus`
version	3.5.0
usage	`import {useFocusRing} from '@react-aria/focus'`

View repository

GitHub

View package

NPM

API#

useFocusRing(
  (props: FocusRingProps
)): 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#

Name	Type	Default	Description
`within`	`boolean`	`'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).
`isTextInput`	`boolean`	—	Whether the element is a text input.
`autoFocus`	`boolean`	—	Whether the element will be auto focused.

Result#

Name	Type	Description
`isFocused`	`boolean`	Whether the element is currently focused.
`isFocusVisible`	`boolean`	Whether keyboard focus should be visible.
`focusProps`	`HTMLAttributes<HTMLElement>`	Props 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.

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>
  );
}

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>
  );
}

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>
  );
}