# useFocusWithin



## Features

`useFocusWithin` handles focus interactions for an element and its descendants. Focus is "within"
an element when either the element itself or a descendant element has focus. This is similar to
the [:focus-within](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-within) pseudo class
in CSS.

To handle focus events on only the target element, and not descendants, see [useFocus](useFocus.md).

## Example

This example stores focus within state in local component state, which is updated by an `onFocusWithinChange` handler. This is used
to update the background color and text color of the group while one of the text fields has focus.

Focus within and blur within events are also logged to the list below. Notice that the events are only
fired when the wrapper gains and loses focus, not when focus moves within the group.

{/* We don't have component hook docs yet */}

{/* **NOTE: for more advanced text field functionality, see [useTextField](useTextField.md).** */}

```tsx
import React from 'react';
import {useFocusWithin} from '@react-aria/interactions';

function Example() {
  let [events, setEvents] = React.useState([]);
  let [isFocusWithin, setFocusWithin] = React.useState(false);
  let {focusWithinProps} = useFocusWithin({
    onFocusWithin: e => setEvents(
      events => [...events, 'focus within']
    ),
    onBlurWithin: e => setEvents(
      events => [...events, 'blur within']
    ),
    onFocusWithinChange: isFocusWithin => setFocusWithin(isFocusWithin)
  });

  return (
    <>
      <div
        {...focusWithinProps}
        style={{
          display: 'inline-block',
          border: '1px solid gray',
          padding: 10,
          background: isFocusWithin ? 'goldenrod' : '',
          color: isFocusWithin ? 'black' : ''
        }}>
        <label style={{display: 'block'}}>
          First Name: <input />
        </label>
        <label style={{display: 'block'}}>
          Last Name: <input />
        </label>
      </div>
      <ul
        style={{
          maxHeight: '200px',
          overflow: 'auto'
        }}>
        {events.map((e, i) => <li key={i}>{e}</li>)}
      </ul>
    </>
  );
}
```

## API

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

### FocusWithinProps

| Name | Type | Description |
|------|------|-------------|
| `isDisabled` | `boolean | undefined` | Whether the focus within events should be disabled. |
| `onFocusWithin` | `((e: FocusEvent) => void) | undefined` | Handler that is called when the target element or a descendant receives focus. |
| `onBlurWithin` | `((e: FocusEvent) => void) | undefined` | Handler that is called when the target element and all descendants lose focus. |
| `onFocusWithinChange` | `((isFocusWithin: boolean) => void) | undefined` | Handler that is called when the the focus within state changes. |

### FocusWithinResult

| Name | Type | Description |
|------|------|-------------|
| `focusWithinProps` \* | `DOMAttributes<FocusableElement>` | Props to spread onto the target element. |