# useFocusRing



## 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](FocusRing.html) component for a shortcut.

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

{/* Not implemented yet */}

{/* See [useCheckbox](useCheckbox.html#styling), [useRadioGroup](useRadioGroup.html#styling), and
[useSwitch](useSwitch.html#example) for more advanced examples of focus rings with other styling
techniques. */}

```tsx
'use client';
import {useFocusRing} from '@react-aria/focus';

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

## API

<FunctionAPI
  links={docs.links}
  function={docs.exports.useFocusRing}
/>

### AriaFocusRingProps

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

### FocusRingAria

| Name | Type | Description |
|------|------|-------------|
| `isFocused` \* | `boolean` | Whether the element is currently focused. |
| `isFocusVisible` \* | `boolean` | Whether keyboard focus should be visible. |
| `focusProps` \* | `DOMAttributes<FocusableElement>` | Props to apply to the container element with the focus ring. |