useKeyboard

Handles keyboard interactions for a focusable element.

installyarn add react-aria
version3.19.0
usageimport {useKeyboard} from 'react-aria'

API#


useKeyboard( (props: KeyboardProps )): KeyboardResult

Features#


useKeyboard handles keyboard interactions. The only difference from DOM events is that propagation is stopped by default if there is an event handler, unless event.continuePropagation() is called. This provides better modularity by default, so that a parent component doesn't respond to an event that a child already handled. If the child doesn't handle the event (e.g. it was for an unknown key), it can call event.continuePropagation() to allow parents to handle the event.

Usage#


useKeyboard returns props that you should spread onto the target element:

NameTypeDescription
keyboardPropsDOMAttributesProps to spread onto the target element.

useKeyboard supports the following event handlers:

NameTypeDescription
onKeyDown( (e: KeyboardEvent )) => voidHandler that is called when a key is pressed.
onKeyUp( (e: KeyboardEvent )) => voidHandler that is called when a key is released.

Example#


This example shows a simple input element that handles keyboard events with useKeyboard and logs them to a list below.

NOTE: for more advanced text field functionality, see useTextField.

import {useKeyboard} from 'react-aria';

function Example() {
  let [events, setEvents] = React.useState([]);
  let { keyboardProps } = useKeyboard({
    onKeyDown: (e) =>
      setEvents(
        (events) => [`key down: ${e.key}`, ...events]
      ),
    onKeyUp: (e) =>
      setEvents(
        (events) => [`key up: ${e.key}`, ...events]
      )
  });

  return (
    <>
      <label htmlFor="example">Example</label>
      <input
        {...keyboardProps}
        id="example"
      />
      <ul
        style={{
          height: 100,
          overflow: 'auto',
          border: '1px solid gray',
          width: 200
        }}
      >
        {events.map((e, i) => <li key={i}>{e}</li>)}
      </ul>
    </>
  );
}
import {useKeyboard} from 'react-aria';

function Example() {
  let [events, setEvents] = React.useState([]);
  let { keyboardProps } = useKeyboard({
    onKeyDown: (e) =>
      setEvents(
        (events) => [`key down: ${e.key}`, ...events]
      ),
    onKeyUp: (e) =>
      setEvents(
        (events) => [`key up: ${e.key}`, ...events]
      )
  });

  return (
    <>
      <label htmlFor="example">Example</label>
      <input
        {...keyboardProps}
        id="example"
      />
      <ul
        style={{
          height: 100,
          overflow: 'auto',
          border: '1px solid gray',
          width: 200
        }}
      >
        {events.map((e, i) => <li key={i}>{e}</li>)}
      </ul>
    </>
  );
}
import {useKeyboard} from 'react-aria';

function Example() {
  let [
    events,
    setEvents
  ] = React.useState([]);
  let { keyboardProps } =
    useKeyboard({
      onKeyDown: (e) =>
        setEvents(
          (events) => [
            `key down: ${e.key}`,
            ...events
          ]
        ),
      onKeyUp: (e) =>
        setEvents(
          (events) => [
            `key up: ${e.key}`,
            ...events
          ]
        )
    });

  return (
    <>
      <label htmlFor="example">
        Example
      </label>
      <input
        {...keyboardProps}
        id="example"
      />
      <ul
        style={{
          height: 100,
          overflow:
            'auto',
          border:
            '1px solid gray',
          width: 200
        }}
      >
        {events.map((
          e,
          i
        ) => (
          <li key={i}>
            {e}
          </li>
        ))}
      </ul>
    </>
  );
}