useFocus
Handles focus events for the immediate target. Focus events on child elements will be ignored.
install | yarn add react-aria |
---|---|
version | 3.33.1 |
usage | import {useFocus} from 'react-aria' |
API#
useFocus<Target extends FocusableElement = FocusableElement>(
(props: FocusProps<Target>
)): FocusResult<Target>
Features#
useFocus
handles focus interactions for an element. Unlike React's built-in focus events,
useFocus
does not fire focus events for child elements of the target. This matches DOM
behavior where focus events do not bubble. This is similar to
the :focus pseudo class
in CSS.
To handle focus events on descendants of an element, see useFocusWithin.
Usage#
useFocus
returns props that you should spread onto the target element:
Name | Type | Description |
focusProps | DOMAttributes<Target> | Props to spread onto the target element. |
useFocus
supports the following event handlers:
Name | Type | Description |
onFocus | (
(e: FocusEvent<Target>
)) => void | Handler that is called when the element receives focus. |
onBlur | (
(e: FocusEvent<Target>
)) => void | Handler that is called when the element loses focus. |
onFocusChange | (
(isFocused: boolean
)) => void | Handler that is called when the element's focus status changes. |
Example#
This example shows a simple input element that handles focus events with useFocus
and logs them to a list below.
NOTE: for more advanced text field functionality, see useTextField.
import {useFocus} from 'react-aria';
function Example() {
let [events, setEvents] = React.useState([]);
let { focusProps } = useFocus({
onFocus: (e) =>
setEvents(
(events) => [...events, 'focus']
),
onBlur: (e) =>
setEvents(
(events) => [...events, 'blur']
),
onFocusChange: (isFocused) =>
setEvents(
(events) => [...events, `focus change: `]
)
});
return (
<>
<label htmlFor="example">Example</label>
<input
{...focusProps}
id="example"
/>
<ul
style={{
maxHeight: '200px',
overflow: 'auto'
}}
>
{events.map((e, i) => <li key={i}>{e}</li>)}
</ul>
</>
);
}
import {useFocus} from 'react-aria';
function Example() {
let [events, setEvents] = React.useState([]);
let { focusProps } = useFocus({
onFocus: (e) =>
setEvents(
(events) => [...events, 'focus']
),
onBlur: (e) =>
setEvents(
(events) => [...events, 'blur']
),
onFocusChange: (isFocused) =>
setEvents(
(events) => [
...events,
`focus change:
`]
)
});
return (
<>
<label htmlFor="example">Example</label>
<input
{...focusProps}
id="example"
/>
<ul
style={{
maxHeight: '200px',
overflow: 'auto'
}}
>
{events.map((e, i) => <li key={i}>{e}</li>)}
</ul>
</>
);
}
import {useFocus} from 'react-aria';
function Example() {
let [
events,
setEvents
] = React.useState([]);
let { focusProps } =
useFocus({
onFocus: (e) =>
setEvents(
(events) => [
...events,
'focus'
]
),
onBlur: (e) =>
setEvents(
(events) => [
...events,
'blur'
]
),
onFocusChange:
(isFocused) =>
setEvents(
(events) => [
...events,
`focus change:
`]
)
});
return (
<>
<label htmlFor="example">
Example
</label>
<input
{...focusProps}
id="example"
/>
<ul
style={{
maxHeight:
'200px',
overflow:
'auto'
}}
>
{events.map((
e,
i
) => (
<li key={i}>
{e}
</li>
))}
</ul>
</>
);
}