# media-hotkey

Register a keyboard shortcut that invokes a player action

## Import

```ts
import '@videojs/html/ui/hotkey';
```

## Anatomy

```html
<media-hotkey keys="Space" action="togglePaused"></media-hotkey>
```

## Behavior

`<media-hotkey>` is a behavior component: it renders no visible interface. Place it inside a [`<media-container>`](https://videojs.org/docs/framework/html/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.

**index.html**

```html
<video-player>
  <media-container class="html-hotkey-basic">
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline></video>
    <p class="html-hotkey-basic__instructions">Space: play/pause · M: mute · ←/→: seek</p>
    <media-play-button class="html-hotkey-basic__button">
      <span class="show-when-paused">Play</span>
      <span class="show-when-playing">Pause</span>
      <span class="show-when-ended">Replay</span>
    </media-play-button>
    <media-hotkey keys="Space" action="togglePaused"></media-hotkey>
    <media-hotkey keys="m" action="toggleMuted"></media-hotkey>
    <media-hotkey keys="ArrowLeft" action="seekStep" value="-5"></media-hotkey>
    <media-hotkey keys="ArrowRight" action="seekStep" value="5"></media-hotkey>
  </media-container>
</video-player>
```

**index.css**

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

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

.html-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;
}

.html-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;
}

.html-hotkey-basic__button .show-when-paused,
.html-hotkey-basic__button .show-when-playing,
.html-hotkey-basic__button .show-when-ended {
  display: none;
}

.html-hotkey-basic__button[data-paused]:not([data-ended]) .show-when-paused,
.html-hotkey-basic__button:not([data-paused]) .show-when-playing,
.html-hotkey-basic__button[data-ended] .show-when-ended {
  display: inline;
}
```

**index.ts**

```ts
import '@videojs/html/video/player';
import '@videojs/html/ui/container';
import '@videojs/html/ui/hotkey';
import '@videojs/html/ui/play-button';
```

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

---

HTML documentation: https://videojs.org/docs/framework/html/llms.txt
All documentation: https://videojs.org/llms.txt