useFullscreenVideo

Simplified cross-browser fullscreen video behavior.

Motivation

This React hook simplifies the process of managing fullscreen video playback across different browsers, handling the complexities of vendor-specific APIs for you. It also handles the fallback scenario, in case the browser (e.g. iOS Safari) does not support setting a HTMLDivElement to fullscreen (but does allow HTMLVideoElement to do so).

Installation

yarn add @kaliber/use-fullscreen-video

Usage

import { useFullscreenElement } from '@kaliber/use-fullscreen-video'

function Component() {
  const { refs, request, exit } = useFullscreenVideo({
    onChange: console.debug,
    onError: console.error
  })

  return (
    <main>
      <div ref={refs.setContainer}>
        <video ref={refs.setVideo} src={neverGonnaGiveYouUp} />
        <button onClick={exit}>
          Exit fullscreen
        </button>
      </div>

      <button onClick={request}>
        Request fullscreen
      </button>
    </main>
  )
}

Third party players

Implementations between third party players may vary. Make sure you have access to the internal video element for the broadest cross-browser support.

using ReactPlayer

import { useFullscreenElement } from '@kaliber/use-fullscreen-video'
import ReactPlayer from 'react-player'

function Component() {
  const videoRef = React.useRef(null)
  const { refs, request, exit } = useFullscreenVideo({
    onChange: console.debug,
    onError: console.error
  })

  return (
    <main>
      <div ref={refs.setContainer}>
        <ReactPlayer 
          ref={videoRef} 
          // Make sure you add a `src` that uses ReactPlayer's `FilePlayer`:
          src={neverGonnaGiveYouUp} 
          onReady={() => {
            // Video ref is only available when video is ready:
            const videoPlayerElement = videoRef.current.getInternalPlayer()
            refs.setVideo(videoPlayerElement)
          }}
        />
        <button onClick={exit}>
          Exit fullscreen
        </button>
      </div>

      <button onClick={request}>
        Request fullscreen
      </button>
    </main>
  )
}

Hook Options

The useFullscreenVideo hook accepts an options object:

• onChange(event): A callback function that is triggered whenever the fullscreen state changes. The isFullscreen argument will be an Event.
• onError(error): A callback function invoked if an error occurs during fullscreen transitions. The error argument will contain the error details.

Returned Values

The hook returns an object containing the following:

Values

• refs: An object with setContainer and setVideo setters for assigning references to the container element and video element, respectively.
• element: The DOM element that is currently in fullscreen mode (if any).
• isFullscreen: A boolean value indicating whether the video is in fullscreen mode.
• isEnabled: A boolean value indicating whether fullscreen functionality is supported by the browser.

Methods

• request(options): Initiates a fullscreen request on either the designated container or the video element itself, depending on browser implementation. The options argument allows for potential browser-specific configuration.
• exit(): Exits the fullscreen mode.

Disclaimer

This library is intended for internal use, we provide no support, use at your own risk. It does not import React, but expects it to be provided, which @kaliber/build can handle for you.

This library is not transpiled.