Skip to content

GuidePlayback

Add keyboard shortcuts and gestures

Add keyboard shortcuts, tap and double-tap gestures, and on-screen feedback for input actions.

Add keyboard shortcuts and pointer gestures to the player declaratively, with on-screen feedback and screen-reader announcements.

Recommended approach

Declare shortcuts with <media-hotkey> and gestures with <media-gesture> inside the player container. Each maps an input to a player action. The packaged skins include bindings suited to their player preset.

<video-player>
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline></video>

    <media-hotkey keys="Space" action="togglePaused"></media-hotkey>
    <media-hotkey keys="m" action="toggleMuted"></media-hotkey>
    <media-hotkey keys="f" action="toggleFullscreen"></media-hotkey>
    <media-hotkey keys="ArrowRight" action="seekStep" value="5"></media-hotkey>
    <media-hotkey keys="ArrowLeft" action="seekStep" value="-5"></media-hotkey>

    <media-gesture type="tap" action="togglePaused" pointer="mouse" region="center"></media-gesture>
    <media-gesture type="tap" action="toggleControls" pointer="touch"></media-gesture>
    <media-gesture type="doubletap" action="seekStep" value="-10" region="left"></media-gesture>
    <media-gesture type="doubletap" action="seekStep" value="10" region="right"></media-gesture>
  </media-container>
</video-player>
<script type="module">
  import '@videojs/html/video/player';
  import '@videojs/html/ui/container';
  import '@videojs/html/ui/hotkey';
  import '@videojs/html/ui/gesture';
</script>

How it works

  • <media-hotkey> binds keys to player actions: togglePaused, toggleMuted, toggleFullscreen, toggleSubtitles, togglePictureInPicture, seekStep, volumeStep, seekToPercent, speedUp, and speedDown. seekStep and volumeStep use a default step unless you pass a custom value. These input actions call the feature actions your components use; for example, toggleFullscreen chooses requestFullscreen or exitFullscreen based on isFullscreen.
  • <media-gesture> binds tap and doubletap to the same actions. Gestures also support toggleControls; seekToPercent is available only to hotkeys. Scope each binding with pointer (mouse or touch) and region (left, center, right). For example, a double tap on the left can rewind while a double tap on the right skips forward.
  • <media-status-announcer> announces action results to screen readers. The input indicator components show brief on-screen feedback, such as volume level or captions on and off, the way native players do. The packaged skins include both.

The on-demand video skins bind these keys:

  • Space and k: play and pause
  • m: mute
  • f: fullscreen
  • c: captions
  • i: picture-in-picture
  • Left and Right arrows, j and l: seek 10 seconds
  • Up and Down arrows: volume
  • 0–9: jump to a percentage
  • < and >: speed

Live video skins keep the playback, mute, volume, fullscreen, captions, and picture-in-picture shortcuts. They omit seeking and speed shortcuts.

How the container splits into regions depends on which regions you bind for the same gesture type and pointer type. Left and right bindings divide the container into halves. Adding a center binding divides it into thirds. A center-only binding covers the whole container; a left-only or right-only binding covers that half. These regions use the container’s width, not the rendered video’s width.

Availability and constraints

  • Hotkeys listen on the player container by default, so multiple players on a page don’t fight over keys. Pass target="document" on a hotkey to make it page-wide — appropriate only when one player owns the page.
  • Typing is protected: while focus is in an editable field, single-key bindings are skipped automatically. Modifier combinations (for example Ctrl+Shift+f) still fire.
  • Repeatable actions (seeking, volume) fire on held keys; toggle actions don’t repeat.
  • Use only one of toggleControls and togglePaused for tap bindings with the same pointer type. The packaged skins pause on a mouse tap and toggle controls on a touch tap, matching platform conventions.
  • Declared gestures and the built-in touch handling share one recognizer. Use the gesture components to add bindings. Extra raw pointer listeners can toggle controls twice.

Common variations

Customize a shortcut

For a packaged skin, add the skin source to your project and edit its <media-hotkey> declarations. Adding another binding alongside the packaged skin does not replace its bindings. For a custom UI, edit your own <media-hotkey> set directly.

Seek step size

Set the seekStep distance with value. Match it to your content: 5 seconds for short clips, 15 or 30 seconds for long-form video.

Troubleshooting

Shortcuts don’t fire

Focus is outside the player container. Click the player first, or move focus into it; hotkeys are player-scoped by design.

Double-tap seek also toggles pause

The built-in recognizer delays a matching single tap and cancels it when a double tap occurs. Check that your tap and double-tap bindings use compatible pointer filters. Remove separate click handlers that also toggle playback, and avoid native video controls on the same gesture surface.

No visual feedback on keyboard actions

The input indicator components render that feedback; use a packaged skin or add <media-status-announcer> and the indicator components from the skin source to a custom UI.

Related pages

Components

API

Guides