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.4
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.