react-hover-video-player - npm Package Compare versions

Comparing version 8.0.2 to 8.1.0

dist/HoverVideoPlayer.types.d.ts

@@ -66,2 +66,9 @@ /// <reference types="react" />
     /**
+     * Provides a custom element that should be used as the target for hover events to start/stop the video.
+     * Accepts a DOM Node, a function which returns a DOM Node, or a React ref.
+     * The component's container div element will be used by default if no hover target is provided.
+     * @defaultValue null
+     */
+    hoverTarget?: Node | (() => Node) | React.RefObject<Node>;
+    /**
      * Ref to a custom element that should be used as the target for hover events to start/stop the video.
@@ -198,2 +205,7 @@ * The component's container div element will be used by default if no hover target ref is provided.
     /**
+     * React ref to forward to the video element rendered by HoverVideoPlayer.
+     * @defaultValue null
+     */
+    videoRef?: React.Ref<HTMLVideoElement>;
+    /**
      * Optional unique ID to apply to the video element.
@@ -200,0 +212,0 @@ * This can be useful for scenarios where you need to manually access

dist/index.esm.js

@@ -1,2 +0,2 @@
-import React, { useState, useRef, useEffect, useMemo } from 'react';
+import React, { useState, useRef, useImperativeHandle, useEffect, useMemo } from 'react';
 
@@ -166,8 +166,8 @@ /*! *****************************************************************************
 var HoverVideoPlayer = function (_a) {
-    var videoSrc = _a.videoSrc, _b = _a.videoCaptions, videoCaptions = _b === void 0 ? null : _b, _c = _a.focused, focused = _c === void 0 ? false : _c, _d = _a.disableDefaultEventHandling, disableDefaultEventHandling = _d === void 0 ? false : _d, _e = _a.hoverTargetRef, hoverTargetRef = _e === void 0 ? null : _e, _f = _a.pausedOverlay, pausedOverlay = _f === void 0 ? null : _f, _g = _a.loadingOverlay, loadingOverlay = _g === void 0 ? null : _g, _h = _a.loadingStateTimeout, loadingStateTimeout = _h === void 0 ? 200 : _h, _j = _a.overlayTransitionDuration, overlayTransitionDuration = _j === void 0 ? 400 : _j, _k = _a.restartOnPaused, restartOnPaused = _k === void 0 ? false : _k, _l = _a.unloadVideoOnPaused, unloadVideoOnPaused = _l === void 0 ? false : _l, _m = _a.muted, muted = _m === void 0 ? true : _m, _o = _a.volume, volume = _o === void 0 ? 1 : _o, _p = _a.loop, loop = _p === void 0 ? true : _p, _q = _a.preload, preload = _q === void 0 ? null : _q, _r = _a.crossOrigin, crossOrigin = _r === void 0 ? 'anonymous' : _r, _s = _a.controls, controls = _s === void 0 ? false : _s, _t = _a.controlsList, controlsList = _t === void 0 ? null : _t, _u = _a.disableRemotePlayback, disableRemotePlayback = _u === void 0 ? true : _u, _v = _a.disablePictureInPicture, disablePictureInPicture = _v === void 0 ? true : _v, _w = _a.className, className = _w === void 0 ? null : _w, _x = _a.style, style = _x === void 0 ? null : _x, _y = _a.pausedOverlayWrapperClassName, pausedOverlayWrapperClassName = _y === void 0 ? null : _y, _z = _a.pausedOverlayWrapperStyle, pausedOverlayWrapperStyle = _z === void 0 ? null : _z, _0 = _a.loadingOverlayWrapperClassName, loadingOverlayWrapperClassName = _0 === void 0 ? null : _0, _1 = _a.loadingOverlayWrapperStyle, loadingOverlayWrapperStyle = _1 === void 0 ? null : _1, _2 = _a.videoId, videoId = _2 === void 0 ? null : _2, _3 = _a.videoClassName, videoClassName = _3 === void 0 ? null : _3, _4 = _a.videoStyle, videoStyle = _4 === void 0 ? null : _4, _5 = _a.sizingMode, sizingMode = _5 === void 0 ? 'video' : _5;
+    var videoSrc = _a.videoSrc, _b = _a.videoCaptions, videoCaptions = _b === void 0 ? null : _b, _c = _a.focused, focused = _c === void 0 ? false : _c, _d = _a.disableDefaultEventHandling, disableDefaultEventHandling = _d === void 0 ? false : _d, _e = _a.hoverTargetRef, hoverTargetRef = _e === void 0 ? null : _e, _f = _a.hoverTarget, hoverTarget = _f === void 0 ? null : _f, _g = _a.pausedOverlay, pausedOverlay = _g === void 0 ? null : _g, _h = _a.loadingOverlay, loadingOverlay = _h === void 0 ? null : _h, _j = _a.loadingStateTimeout, loadingStateTimeout = _j === void 0 ? 200 : _j, _k = _a.overlayTransitionDuration, overlayTransitionDuration = _k === void 0 ? 400 : _k, _l = _a.restartOnPaused, restartOnPaused = _l === void 0 ? false : _l, _m = _a.unloadVideoOnPaused, unloadVideoOnPaused = _m === void 0 ? false : _m, _o = _a.muted, muted = _o === void 0 ? true : _o, _p = _a.volume, volume = _p === void 0 ? 1 : _p, _q = _a.loop, loop = _q === void 0 ? true : _q, _r = _a.preload, preload = _r === void 0 ? null : _r, _s = _a.crossOrigin, crossOrigin = _s === void 0 ? 'anonymous' : _s, _t = _a.controls, controls = _t === void 0 ? false : _t, _u = _a.controlsList, controlsList = _u === void 0 ? null : _u, _v = _a.disableRemotePlayback, disableRemotePlayback = _v === void 0 ? true : _v, _w = _a.disablePictureInPicture, disablePictureInPicture = _w === void 0 ? true : _w, _x = _a.className, className = _x === void 0 ? null : _x, _y = _a.style, style = _y === void 0 ? null : _y, _z = _a.pausedOverlayWrapperClassName, pausedOverlayWrapperClassName = _z === void 0 ? null : _z, _0 = _a.pausedOverlayWrapperStyle, pausedOverlayWrapperStyle = _0 === void 0 ? null : _0, _1 = _a.loadingOverlayWrapperClassName, loadingOverlayWrapperClassName = _1 === void 0 ? null : _1, _2 = _a.loadingOverlayWrapperStyle, loadingOverlayWrapperStyle = _2 === void 0 ? null : _2, _3 = _a.videoId, videoId = _3 === void 0 ? null : _3, _4 = _a.videoClassName, videoClassName = _4 === void 0 ? null : _4, _5 = _a.videoRef, forwardedVideoRef = _5 === void 0 ? null : _5, _6 = _a.videoStyle, videoStyle = _6 === void 0 ? null : _6, _7 = _a.sizingMode, sizingMode = _7 === void 0 ? 'video' : _7;
     // Keep track of whether the user is hovering over the video and it should therefore be playing or not
-    var _6 = useState(false), isHoveringOverVideo = _6[0], setIsHoveringOverVideo = _6[1];
+    var _8 = useState(false), isHoveringOverVideo = _8[0], setIsHoveringOverVideo = _8[1];
     // Keep track of how the paused and loading overlays should be displayed
-    var _7 = useState(OverlayState.paused), overlayState = _7[0], setOverlayState = _7[1];
-    var _8 = useState(true), isVideoPaused = _8[0], setIsVideoPaused = _8[1];
+    var _9 = useState(OverlayState.paused), overlayState = _9[0], setOverlayState = _9[1];
+    var _10 = useState(true), isVideoPaused = _10[0], setIsVideoPaused = _10[1];
     // Keep a ref for all state variables related to the video's state
@@ -194,2 +194,4 @@ // which need to be managed asynchronously as it attempts to play/pause
     var videoRef = useRef(null);
+    // Forward out local videoRef along to the videoRef prop
+    useImperativeHandle(forwardedVideoRef, function () { return videoRef.current; });
     var hasPausedOverlay = Boolean(pausedOverlay);
@@ -296,5 +298,31 @@ var hasLoadingOverlay = Boolean(loadingOverlay);
             return undefined;
-        // If a ref to a custom hover target was provided, we'll use that as our target element,
-        // but otherwise just default to our container element
-        var hoverTargetElement = (hoverTargetRef || containerRef).current;
+        // Get the element that we should add our hover event listeners to
+        var hoverEventTargetElement;
+        if (hoverTarget) {
+            // If the `hoverTarget` prop was provided, it could be a function, a DOM element, or a React ref, so
+            // figure out which one it is and get the hover target element out of it accordingly
+            if (typeof hoverTarget === 'function') {
+                hoverEventTargetElement = hoverTarget();
+            }
+            else if (hoverTarget instanceof Node) {
+                hoverEventTargetElement = hoverTarget;
+            }
+            else if (hoverTarget.current) {
+                hoverEventTargetElement = hoverTarget.current;
+            }
+        }
+        else if (hoverTargetRef) {
+            // Log a warning for legacy usage of the `hoverTargetRef` prop
+            console.warn('The `hoverTargetRef` prop is deprecated in favor of `hoverTarget` and will be removed in the next major version of `react-hover-video-player`. To migrate, simply rename the prop to `hoverTarget` and it should continue working as intended.');
+            hoverEventTargetElement = hoverTargetRef.current;
+        }
+        else {
+            // If no prop was provided to specify a hover target, default to using HoverVideoPlayer's container element
+            hoverEventTargetElement = containerRef.current;
+        }
+        // If we weren't able to get a valid hover target to attach event listeners to, return early
+        if (!hoverEventTargetElement || !hoverEventTargetElement.addEventListener) {
+            console.error('HoverVideoPlayer was unable to add event listeners to a hover target. Please check your usage of the `hoverTarget` prop.');
+            return undefined;
+        }
         // Add the event listeners
@@ -304,12 +332,12 @@ var onHoverStart = function () { return setIsHoveringOverVideo(true); };
         // Mouse events
-        hoverTargetElement.addEventListener('mouseenter', onHoverStart);
-        hoverTargetElement.addEventListener('mouseleave', onHoverEnd);
+        hoverEventTargetElement.addEventListener('mouseenter', onHoverStart);
+        hoverEventTargetElement.addEventListener('mouseleave', onHoverEnd);
         // Focus/blur
-        hoverTargetElement.addEventListener('focus', onHoverStart);
-        hoverTargetElement.addEventListener('blur', onHoverEnd);
+        hoverEventTargetElement.addEventListener('focus', onHoverStart);
+        hoverEventTargetElement.addEventListener('blur', onHoverEnd);
         // Touch events
-        hoverTargetElement.addEventListener('touchstart', onHoverStart);
+        hoverEventTargetElement.addEventListener('touchstart', onHoverStart);
         // Event listener pauses the video when the user touches somewhere outside of the player
         var onWindowTouchStart = function (event) {
-            if (!hoverTargetElement.contains(event.target)) {
+            if (!hoverEventTargetElement.contains(event.target)) {
                 onHoverEnd();
@@ -321,10 +349,10 @@ }
         return function () {
-            hoverTargetElement.removeEventListener('mouseenter', onHoverStart);
-            hoverTargetElement.removeEventListener('mouseleave', onHoverEnd);
-            hoverTargetElement.removeEventListener('focus', onHoverStart);
-            hoverTargetElement.removeEventListener('blur', onHoverEnd);
-            hoverTargetElement.removeEventListener('touchstart', onHoverStart);
+            hoverEventTargetElement.removeEventListener('mouseenter', onHoverStart);
+            hoverEventTargetElement.removeEventListener('mouseleave', onHoverEnd);
+            hoverEventTargetElement.removeEventListener('focus', onHoverStart);
+            hoverEventTargetElement.removeEventListener('blur', onHoverEnd);
+            hoverEventTargetElement.removeEventListener('touchstart', onHoverStart);
             window.removeEventListener('touchstart', onWindowTouchStart);
         };
-    }, [disableDefaultEventHandling, hoverTargetRef]);
+    }, [disableDefaultEventHandling, hoverTarget, hoverTargetRef]);
     // Effect sets attributes on the video which can't be done via props
@@ -331,0 +359,0 @@ useEffect(function () {

dist/index.js

@@ -172,8 +172,8 @@ 'use strict';
 var HoverVideoPlayer = function (_a) {
-    var videoSrc = _a.videoSrc, _b = _a.videoCaptions, videoCaptions = _b === void 0 ? null : _b, _c = _a.focused, focused = _c === void 0 ? false : _c, _d = _a.disableDefaultEventHandling, disableDefaultEventHandling = _d === void 0 ? false : _d, _e = _a.hoverTargetRef, hoverTargetRef = _e === void 0 ? null : _e, _f = _a.pausedOverlay, pausedOverlay = _f === void 0 ? null : _f, _g = _a.loadingOverlay, loadingOverlay = _g === void 0 ? null : _g, _h = _a.loadingStateTimeout, loadingStateTimeout = _h === void 0 ? 200 : _h, _j = _a.overlayTransitionDuration, overlayTransitionDuration = _j === void 0 ? 400 : _j, _k = _a.restartOnPaused, restartOnPaused = _k === void 0 ? false : _k, _l = _a.unloadVideoOnPaused, unloadVideoOnPaused = _l === void 0 ? false : _l, _m = _a.muted, muted = _m === void 0 ? true : _m, _o = _a.volume, volume = _o === void 0 ? 1 : _o, _p = _a.loop, loop = _p === void 0 ? true : _p, _q = _a.preload, preload = _q === void 0 ? null : _q, _r = _a.crossOrigin, crossOrigin = _r === void 0 ? 'anonymous' : _r, _s = _a.controls, controls = _s === void 0 ? false : _s, _t = _a.controlsList, controlsList = _t === void 0 ? null : _t, _u = _a.disableRemotePlayback, disableRemotePlayback = _u === void 0 ? true : _u, _v = _a.disablePictureInPicture, disablePictureInPicture = _v === void 0 ? true : _v, _w = _a.className, className = _w === void 0 ? null : _w, _x = _a.style, style = _x === void 0 ? null : _x, _y = _a.pausedOverlayWrapperClassName, pausedOverlayWrapperClassName = _y === void 0 ? null : _y, _z = _a.pausedOverlayWrapperStyle, pausedOverlayWrapperStyle = _z === void 0 ? null : _z, _0 = _a.loadingOverlayWrapperClassName, loadingOverlayWrapperClassName = _0 === void 0 ? null : _0, _1 = _a.loadingOverlayWrapperStyle, loadingOverlayWrapperStyle = _1 === void 0 ? null : _1, _2 = _a.videoId, videoId = _2 === void 0 ? null : _2, _3 = _a.videoClassName, videoClassName = _3 === void 0 ? null : _3, _4 = _a.videoStyle, videoStyle = _4 === void 0 ? null : _4, _5 = _a.sizingMode, sizingMode = _5 === void 0 ? 'video' : _5;
+    var videoSrc = _a.videoSrc, _b = _a.videoCaptions, videoCaptions = _b === void 0 ? null : _b, _c = _a.focused, focused = _c === void 0 ? false : _c, _d = _a.disableDefaultEventHandling, disableDefaultEventHandling = _d === void 0 ? false : _d, _e = _a.hoverTargetRef, hoverTargetRef = _e === void 0 ? null : _e, _f = _a.hoverTarget, hoverTarget = _f === void 0 ? null : _f, _g = _a.pausedOverlay, pausedOverlay = _g === void 0 ? null : _g, _h = _a.loadingOverlay, loadingOverlay = _h === void 0 ? null : _h, _j = _a.loadingStateTimeout, loadingStateTimeout = _j === void 0 ? 200 : _j, _k = _a.overlayTransitionDuration, overlayTransitionDuration = _k === void 0 ? 400 : _k, _l = _a.restartOnPaused, restartOnPaused = _l === void 0 ? false : _l, _m = _a.unloadVideoOnPaused, unloadVideoOnPaused = _m === void 0 ? false : _m, _o = _a.muted, muted = _o === void 0 ? true : _o, _p = _a.volume, volume = _p === void 0 ? 1 : _p, _q = _a.loop, loop = _q === void 0 ? true : _q, _r = _a.preload, preload = _r === void 0 ? null : _r, _s = _a.crossOrigin, crossOrigin = _s === void 0 ? 'anonymous' : _s, _t = _a.controls, controls = _t === void 0 ? false : _t, _u = _a.controlsList, controlsList = _u === void 0 ? null : _u, _v = _a.disableRemotePlayback, disableRemotePlayback = _v === void 0 ? true : _v, _w = _a.disablePictureInPicture, disablePictureInPicture = _w === void 0 ? true : _w, _x = _a.className, className = _x === void 0 ? null : _x, _y = _a.style, style = _y === void 0 ? null : _y, _z = _a.pausedOverlayWrapperClassName, pausedOverlayWrapperClassName = _z === void 0 ? null : _z, _0 = _a.pausedOverlayWrapperStyle, pausedOverlayWrapperStyle = _0 === void 0 ? null : _0, _1 = _a.loadingOverlayWrapperClassName, loadingOverlayWrapperClassName = _1 === void 0 ? null : _1, _2 = _a.loadingOverlayWrapperStyle, loadingOverlayWrapperStyle = _2 === void 0 ? null : _2, _3 = _a.videoId, videoId = _3 === void 0 ? null : _3, _4 = _a.videoClassName, videoClassName = _4 === void 0 ? null : _4, _5 = _a.videoRef, forwardedVideoRef = _5 === void 0 ? null : _5, _6 = _a.videoStyle, videoStyle = _6 === void 0 ? null : _6, _7 = _a.sizingMode, sizingMode = _7 === void 0 ? 'video' : _7;
     // Keep track of whether the user is hovering over the video and it should therefore be playing or not
-    var _6 = React.useState(false), isHoveringOverVideo = _6[0], setIsHoveringOverVideo = _6[1];
+    var _8 = React.useState(false), isHoveringOverVideo = _8[0], setIsHoveringOverVideo = _8[1];
     // Keep track of how the paused and loading overlays should be displayed
-    var _7 = React.useState(OverlayState.paused), overlayState = _7[0], setOverlayState = _7[1];
-    var _8 = React.useState(true), isVideoPaused = _8[0], setIsVideoPaused = _8[1];
+    var _9 = React.useState(OverlayState.paused), overlayState = _9[0], setOverlayState = _9[1];
+    var _10 = React.useState(true), isVideoPaused = _10[0], setIsVideoPaused = _10[1];
     // Keep a ref for all state variables related to the video's state
@@ -200,2 +200,4 @@ // which need to be managed asynchronously as it attempts to play/pause
     var videoRef = React.useRef(null);
+    // Forward out local videoRef along to the videoRef prop
+    React.useImperativeHandle(forwardedVideoRef, function () { return videoRef.current; });
     var hasPausedOverlay = Boolean(pausedOverlay);
@@ -302,5 +304,31 @@ var hasLoadingOverlay = Boolean(loadingOverlay);
             return undefined;
-        // If a ref to a custom hover target was provided, we'll use that as our target element,
-        // but otherwise just default to our container element
-        var hoverTargetElement = (hoverTargetRef || containerRef).current;
+        // Get the element that we should add our hover event listeners to
+        var hoverEventTargetElement;
+        if (hoverTarget) {
+            // If the `hoverTarget` prop was provided, it could be a function, a DOM element, or a React ref, so
+            // figure out which one it is and get the hover target element out of it accordingly
+            if (typeof hoverTarget === 'function') {
+                hoverEventTargetElement = hoverTarget();
+            }
+            else if (hoverTarget instanceof Node) {
+                hoverEventTargetElement = hoverTarget;
+            }
+            else if (hoverTarget.current) {
+                hoverEventTargetElement = hoverTarget.current;
+            }
+        }
+        else if (hoverTargetRef) {
+            // Log a warning for legacy usage of the `hoverTargetRef` prop
+            console.warn('The `hoverTargetRef` prop is deprecated in favor of `hoverTarget` and will be removed in the next major version of `react-hover-video-player`. To migrate, simply rename the prop to `hoverTarget` and it should continue working as intended.');
+            hoverEventTargetElement = hoverTargetRef.current;
+        }
+        else {
+            // If no prop was provided to specify a hover target, default to using HoverVideoPlayer's container element
+            hoverEventTargetElement = containerRef.current;
+        }
+        // If we weren't able to get a valid hover target to attach event listeners to, return early
+        if (!hoverEventTargetElement || !hoverEventTargetElement.addEventListener) {
+            console.error('HoverVideoPlayer was unable to add event listeners to a hover target. Please check your usage of the `hoverTarget` prop.');
+            return undefined;
+        }
         // Add the event listeners
@@ -310,12 +338,12 @@ var onHoverStart = function () { return setIsHoveringOverVideo(true); };
         // Mouse events
-        hoverTargetElement.addEventListener('mouseenter', onHoverStart);
-        hoverTargetElement.addEventListener('mouseleave', onHoverEnd);
+        hoverEventTargetElement.addEventListener('mouseenter', onHoverStart);
+        hoverEventTargetElement.addEventListener('mouseleave', onHoverEnd);
         // Focus/blur
-        hoverTargetElement.addEventListener('focus', onHoverStart);
-        hoverTargetElement.addEventListener('blur', onHoverEnd);
+        hoverEventTargetElement.addEventListener('focus', onHoverStart);
+        hoverEventTargetElement.addEventListener('blur', onHoverEnd);
         // Touch events
-        hoverTargetElement.addEventListener('touchstart', onHoverStart);
+        hoverEventTargetElement.addEventListener('touchstart', onHoverStart);
         // Event listener pauses the video when the user touches somewhere outside of the player
         var onWindowTouchStart = function (event) {
-            if (!hoverTargetElement.contains(event.target)) {
+            if (!hoverEventTargetElement.contains(event.target)) {
                 onHoverEnd();
@@ -327,10 +355,10 @@ }
         return function () {
-            hoverTargetElement.removeEventListener('mouseenter', onHoverStart);
-            hoverTargetElement.removeEventListener('mouseleave', onHoverEnd);
-            hoverTargetElement.removeEventListener('focus', onHoverStart);
-            hoverTargetElement.removeEventListener('blur', onHoverEnd);
-            hoverTargetElement.removeEventListener('touchstart', onHoverStart);
+            hoverEventTargetElement.removeEventListener('mouseenter', onHoverStart);
+            hoverEventTargetElement.removeEventListener('mouseleave', onHoverEnd);
+            hoverEventTargetElement.removeEventListener('focus', onHoverStart);
+            hoverEventTargetElement.removeEventListener('blur', onHoverEnd);
+            hoverEventTargetElement.removeEventListener('touchstart', onHoverStart);
             window.removeEventListener('touchstart', onWindowTouchStart);
         };
-    }, [disableDefaultEventHandling, hoverTargetRef]);
+    }, [disableDefaultEventHandling, hoverTarget, hoverTargetRef]);
     // Effect sets attributes on the video which can't be done via props
@@ -337,0 +365,0 @@ React.useEffect(function () {

package.json

 {
   "name": "react-hover-video-player",
-  "version": "8.0.2",
+  "version": "8.1.0",
   "description": "React component which manages playing a video when the user hovers over it and pausing when they stop.",
@@ -17,3 +17,3 @@ "main": "dist/index.js",
     "test:debug": "node --inspect-brk node_modules/.bin/jest --runInBand --config=tests/jest.dev.config.js",
-    "docs": "npm run build && npx docsify serve docs",
+    "docs": "npx concurrently --kill-others 'npx gulp watch-docs' 'npx docsify serve docs'",
     "commit": "npx git-cz"
@@ -49,2 +49,3 @@ },
     "commitizen": "^4.2.3",
+    "concurrently": "^6.1.0",
     "cz-conventional-changelog": "^3.2.0",
@@ -62,2 +63,3 @@ "docsify-cli": "^4.4.3",
     "eslint-plugin-testing-library": "^3.0.2",
+    "gulp": "^4.0.2",
     "husky": "^5.1.3",
@@ -70,3 +72,2 @@ "jest": "^25.5.4",
     "rollup": "^2.45.2",
-    "rollup-plugin-copy": "^3.4.0",
     "rollup-plugin-livereload": "^2.0.0",
@@ -73,0 +74,0 @@ "rollup-plugin-node-resolve": "^5.2.0",

README.md

@@ -255,18 +255,35 @@ # React Hover Video Player
 
-### hoverTargetRef
+### hoverTarget
 
-**Type**: `RefObject` | **Default**: `null`
+**Type**: `Node`, a function that returns a `Node`, or a `React.RefObject` | **Default**: `null`
 
-`hoverTargetRef` accepts a React ref to the element that you would like to apply the component's [default event handling](#how-it-works) to. If no ref is provided, it will use the component's container `<div>` as the hover target. This prop is useful if you would like a simple way to make the video play when the user hovers over a larger surrounding area.
+`hoverTarget` accepts a DOM node, a function that returns a DOM node, or a React ref to an element. The component will apply the component's [default event handling](#how-it-works) to the received element. If no `hoverTarget` is provided, HoverVideoPlayer will use the component's container `<div>` as the hover target. A common use case for this would be to make the video play when the user hovers over a larger area around the player.
 
 ```jsx
-const wrapperLinkRef = useRef();
+// Passing a DOM node
+<HoverVideoPlayer
+  videoSrc="video.mp4"
+  // Play the video when the user hovers over the element with id "hover-target"
+  hoverTarget={document.getElementById("hover-target")}
+/>
 
 ...
 
+// Passing a function that returns a DOM node
+<HoverVideoPlayer
+  videoSrc="video.mp4"
+  // Play the video when the user hovers over the element with id "hover-target"
+  hoverTarget={() => document.getElementById("hover-target")}
+/>
+
+...
+
+// Using a React ref
+const wrapperLinkRef = useRef();
+
 <a href="/other-page" ref={wrapperLinkRef}>
   <HoverVideoPlayer
     videoSrc="video.mp4"
-    // We want the video to play when the wrapping link element is hovered or focused
-    hoverTargetRef={wrapperLinkRef}
+  // Play the video when the user hovers over the wrapper link
+    hoverTarget={wrapperLinkRef}
   />
@@ -276,4 +293,2 @@ </a>
 
-Note that this is only intended to work with refs created by React's `useRef` or `createRef` functions; custom callback refs will not work.
-
 ### focused
@@ -290,3 +305,3 @@
 
-<button 
+<button
   // Clicking this button should toggle whether the video is playing
@@ -389,18 +404,21 @@ onClick={()=>setIsVideoPlaying(!isVideoPlaying)}
 
-### videoId
+### videoRef
 
-**Type**: `string` | **Default**: null
+**Type**: `React.Ref` | **Default**: null
 
-`videoId` can be used to set an `id` on the video element. This can be useful if you need to access the video element via `document.getElementById()` in order to extend its behavior in some unique way.
+`videoRef` can be used to expose a ref to the video element rendered by HoverVideoPlayer. This is useful if you need to directly access the video element to extend its behavior in some way, but beware that any changes you make could produce unexpected behavior from the component.
 
 ```jsx
+const hoverVideoRef = useRef();
+
 useEffect(()=>{
-  const videoElement = document.getElementById('hover-video');
-  // DO SOMETHING WITH THE VIDEO ELEMENT HERE
-},[]);
+  const videoElement = hoverVideoRef.current;
 
+  videoElement.playbackRate = 2;
+}, []);
+
 return (
   <HoverVideoPlayer
     videoSrc="video.mp4"
-    videoId="hover-video"
+    videoRef={hoverVideoRef}
   />
@@ -445,2 +463,4 @@ )
   videoClassName="player-video"
+  // Applies an id to the video element
+  videoId="hover-video"
   // Applies inline styles to the video element
@@ -447,0 +467,0 @@ videoStyle={{

No alert changes

Improved metrics

Total package byte prevSize

185114

increased by5.6%

Lines of code

1140

increased by6.34%

Number of lines in readme file

600

increased by3.45%

Worsened metrics

Dev dependency count

51

increased by2%

No dependency changes