Skip to content

GuidePlayback

Go fullscreen and lock orientation

Present the player fullscreen with custom controls intact, and lock screen orientation on mobile.

Recommended approach

Add a <media-fullscreen-button> inside the player container. When element fullscreen is supported, it presents the whole container, including controls, captions, and overlays. On iPhone Safari, it uses the native video presentation instead.

Exit Fullscreen Fullscreen 
<video-player class="video-player">
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" autoplay muted playsinline loop></video>
    <media-fullscreen-button class="media-fullscreen-button">
      <span class="fullscreen">Exit Fullscreen</span>
      <span class="not-fullscreen">Fullscreen</span>
    </media-fullscreen-button>
  </media-container>
</video-player>

How it works

The fullscreen feature tracks fullscreen state and provides the actions:

  • isFullscreen is true while the player is fullscreen, from any path — your button, native controls, or the platform presentation.
  • fullscreenAvailability is 'available', 'unavailable', or 'unsupported'. It starts as 'unavailable', then settles to 'available' or 'unsupported' when the feature attaches to a media component.
  • requestFullscreen() and exitFullscreen() change the presentation. When the Fullscreen API is available, requests target the player container. Otherwise they fall back to the media element’s native presentation.

Fullscreen and picture-in-picture are exclusive: requesting fullscreen exits an active picture-in-picture presentation first.

Style fullscreen state through the container’s :fullscreen pseudo-class, the button’s data-fullscreen attribute, or isFullscreen in player state.

The built-in button hides when fullscreenAvailability is not 'available'. Use the same check for custom controls and handle rejected requests. When the attached media has no supported fullscreen method, the action resolves without changing the presentation.

Availability and constraints

  • Fullscreen requests must come from a user gesture; browsers reject requests outside one.
  • iPhone Safari has no element Fullscreen API. The player falls back to the video’s native fullscreen presentation, which shows the system player UI instead of your custom controls. iPads support element fullscreen.
  • Orientation locking requires the Screen Orientation API with lock support — in practice, Android browsers in fullscreen. iOS doesn’t support programmatic orientation lock.
  • Inside iframes, fullscreen needs allow="fullscreen" on the embedding iframe.

Common variations

Lock orientation while fullscreen

Add orientationLockFeature to lock screen orientation while the player is fullscreen. It isn’t part of videoFeatures, so the preset <video-player> doesn’t include it. It locks to landscape by default and unlocks on exit.

Register a custom player tag with createPlayer:

<orientation-player>
  <media-container>
    <video src="https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4" muted playsinline></video>
    <media-fullscreen-button>Fullscreen</media-fullscreen-button>
  </media-container>
</orientation-player>
<script type="module">
  import { createPlayer, orientationLockFeature } from '@videojs/html';
  import { videoFeatures } from '@videojs/html/video';
  import '@videojs/html/ui/container';
  import '@videojs/html/ui/fullscreen-button';

  const { PlayerElement } = createPlayer({
    features: [...videoFeatures, orientationLockFeature],
  });

  customElements.define('orientation-player', PlayerElement);
</script>

To lock to something other than landscape, set the orientation-lock-type attribute on the player. See the orientation lock feature reference for details.

Double-click to toggle

Use the <media-gesture> element — the packaged skins ship this exact binding. Keep the button as the accessible path; gestures are a pointer-only shortcut.

<media-gesture type="doubletap" action="toggleFullscreen" region="center"></media-gesture>
<script type="module">
  import '@videojs/html/ui/gesture';
</script>

With left, center, and right double-tap bindings for the same pointer type, region="center" covers the middle third, as in the on-demand video skins. A center-only double-tap binding covers the whole surface. See Add keyboard shortcuts and gestures for region behavior.

Troubleshooting

The fullscreen button doesn’t render

The button hides while fullscreenAvailability is 'unavailable' or 'unsupported'. Wait for media attachment, check browser support, and confirm that an embedding iframe permits fullscreen with allow="fullscreen".

The fullscreen request is rejected

Call the action directly from a click handler and check that an embedding iframe permits fullscreen with allow="fullscreen". Handle the returned promise’s rejection. To detect unsupported fullscreen, check fullscreenAvailability; an unsupported request can resolve without entering fullscreen.

Custom controls disappear in fullscreen on iPhone

Expected: iPhone Safari uses the native video presentation, which replaces custom UI with system controls. Design mobile controls assuming this fallback.

Orientation doesn’t lock

Orientation lock works in fullscreen on Android browsers; iOS doesn’t support it. Confirm orientationLockFeature is in your feature list.

Related pages

Components

API

Guides