ImportantFor autoPlay to work reliably across all browsers, the video element MUST have the muted and playsInline attributes set. Most browsers will block unmuted autoplay.
TipThis hook depends on useIntersectionObserver. Ensure that the parent container doesn't have overflow: hidden in a way that prevents the observer from detecting visibility correctly.
NoteThe threshold value determines how much of the video must be visible before autoPlay triggers. A value of 0.5 means 50% of the video must be in the viewport.
The useSmartVideo leverages the useIntersectionObserver to trigger video actions based on the element's visibility in the viewport. It is ideal for social media feeds or landing pages where videos should play automatically when visible and pause or reset when scrolled out of view. It includes safety checks for browser autoplay policies (requiring muted and playsInline) and manages the internal playback state reactively.
| Name | Type | Description |
|---|---|---|
| options.autoPlay | boolean | If true, the video plays automatically when it becomes visible. Default: 'false'. |
| options.pauseOnExit | boolean | If true, the video pauses when it leaves the viewport. Default: 'false'. |
| options.resetOnExit | boolean | If true, resets the video to the beginning when it leaves the viewport. Default: 'false'. |
| options.threshold | number | Visibility ratio (0.0 to 1.0) required to trigger 'visible' state. Default: 0.5. |
| Name | Type | Description |
|---|---|---|
| videoRef | React.RefObject<HTMLVideoElement | null> | The ref to be assigned to the <video> element. |
| isPlaying | boolean | Reactive state indicating if the video is currently playing. |
| isVisible | boolean | Reactive state indicating if the video is currently within the viewport threshold. |
| play | () => Promise<void> | Imperative function to start video playback. |
| pause | () => void | Imperative function to pause video playback. |
| stop | () => void | Pauses the video and resets currentTime to 0. |
| reset | () => void | Resets currentTime to 0 without changing the playback state. |