# Hotkey

Register a keyboard shortcut that invokes a player action

## Import

```tsx
import { Hotkey } from '@videojs/react';
```

## Anatomy

```tsx
<Hotkey keys="Space" action="togglePaused" />
```

## Behavior

`Hotkey` is a behavior component: it renders no visible interface. Place it inside a [Container](https://videojs.org/docs/framework/react/reference/components/player-container) to register one key pattern and player action.

By default, the shortcut responds while the player container has focus. Set `target="document"` only when the shortcut should apply across the entire document.

Key patterns are case-insensitive and may use:

- Named keys such as `Space`, `ArrowLeft`, and `ArrowRight`.
- Exact modifiers such as `Ctrl+k`, `Shift+f`, `Alt+m`, and `Meta+k`.
- `Mod` for `Meta` on macOS and `Ctrl` elsewhere.
- The special `0-9` range for digit-based seeking.

Choose an `action` from the API reference below. Pass `value` as seconds for `seekStep`, a volume delta such as `0.05` or `-0.05` for `volumeStep`, or a percentage from 0 to 100 for `seekToPercent`. When omitted, `seekStep` defaults to 10 seconds and `volumeStep` defaults to five percentage points; `ArrowLeft`, `j`, and `ArrowDown` use the negative step. When `value` is omitted from `seekToPercent` with `keys="0-9"`, the pressed digit supplies the percentage.

Toggle actions ignore held-key repeats. Step, rate, and percentage actions may repeat. A matched shortcut prevents the browser’s default behavior. Unmodified shortcuts are ignored in editable fields, and Space or Enter still activates focused buttons, links, and sliders normally.

## Accessibility

Hotkeys supplement operable controls; they should never be the only way to perform an action. Built-in buttons use matching hotkey registrations to expose `aria-keyshortcuts`, and their tooltips can display the registered shortcut.

## Examples

### Basic Usage

This player uses Space to play or pause, M to mute, and the arrow keys to seek by five seconds. Click the player first to focus its container.

**App.tsx**

```tsx
import { Container, createPlayer, Hotkey, PlayButton } from '@videojs/react';
import { Video, videoFeatures } from '@videojs/react/video';

const { Player } = createPlayer({ features: videoFeatures });

export default function BasicUsage() {
  return (
    <Player>
      <Container className="react-hotkey-basic">
        <Video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsInline />
        <p className="react-hotkey-basic__instructions">Space: play/pause · M: mute · ←/→: seek</p>
        <PlayButton
          className="react-hotkey-basic__button"
          render={(props, state) => (
            <button {...props}>{state.ended ? 'Replay' : state.paused ? 'Play' : 'Pause'}</button>
          )}
        />
        <Hotkey keys="Space" action="togglePaused" />
        <Hotkey keys="m" action="toggleMuted" />
        <Hotkey keys="ArrowLeft" action="seekStep" value={-5} />
        <Hotkey keys="ArrowRight" action="seekStep" value={5} />
      </Container>
    </Player>
  );
}
```

**App.css**

```css
.react-hotkey-basic {
  position: relative;
}

.react-hotkey-basic video {
  width: 100%;
}

.react-hotkey-basic__instructions {
  position: absolute;
  top: 10px;
  left: 10px;
  padding: 6px 10px;
  margin: 0;
  color: white;
  background: rgb(0 0 0 / 70%);
  border-radius: 4px;
}

.react-hotkey-basic__button {
  position: absolute;
  bottom: 10px;
  left: 10px;
  padding: 8px 20px;
  color: black;
  cursor: pointer;
  background: rgb(255 255 255 / 80%);
  border: 1px solid rgb(255 255 255 / 30%);
  border-radius: 9999px;
}
```

## API Reference

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `action` (required) | `'togglePaused' \| 'toggleMuted' \| 'toggleFullscreen' \| 'toggleSubtitles' \| 'togglePictureInPicture' \| 'seekStep' \| 'volumeStep' \| 'speedUp' \| 'speedDown' \| 'seekToPercent'` | — | Player action to run when the key pattern matches. |
| `keys` (required) | `string` | — | Key pattern to match, such as `Space`, `ArrowRight`, or `Mod+k`. |
| `disabled` | `boolean` | — | Whether the hotkey is disabled. |
| `target` | `'player' \| 'document'` | — | Whether to listen on the player container or the document. |
| `value` | `number` | — | Numeric value passed to actions such as `seekStep`, `volumeStep`, and `seekToPercent`. Arrow-key seek and volume actions use their shared input-action step when omitted. |

---

React documentation: https://videojs.org/docs/framework/react/llms.txt
All documentation: https://videojs.org/llms.txt