react-vimeo-progress v1.2.3
React vimeo Progress
A lean responsive wrapper around the vimeo player. This packages exposes a single VimeoPlayer
component and simplifies user progress tracking.
vimeo Player
vimeo is a great platform to host your company's or private videos and the player can be integrated easily into your React application.
Considerations 🤔
There are a few things you should know before installing this package or the original vimeo player.
vimeo Platform 💸
The vimeo player only works with videos hosted on vimeo.com.
The pricing on vimeo is fair and competitive but there are different pricing tiers and you should have a look before installing this component.
Cookies 🍪
The vimeo player uses cookies to track several analytics data points for you to access on the vimeo platform.
The cookies are also used to offer logged-in vimeo users social features (like, comment) right from your embedded video player (which you can disable on vimeo.com).
This is no other than what the embedded YouTube player is doing but you should be aware that vimeo uses cookies as third-party cookies are regulated in several regions.
Responsiveness 📱
The official vimeo player package offers responsive height and width options and user progress tracking is very straight forward to implement. I would first try to make the offical package work. I personally ran into issues with the progressive feature. Feel free to get inspired by the code on GitHub or just install this package if it solves your issues with the offical player!
Installation
npm i react-vimeo-progress
Documentation 📖
This component tracks user progress and allows progressive breakpoints.
It is built with TypeScript and should be typed out of the box.
The VimeoPlayer component can be imported like so:
import VimeoPlayer from 'react-vimeo-progress';
The component takes the following properties:
- id: string
- link: string
- progressInterval?: number
- onProgress?: (progress: number) => void
- onVideoPaused?: () => void
- onVideoEnded?: () => void
- latestProgress?: number
- widthPercentage?: number
- smWidthPercentage?: number
- mdWidthPercentage?: number
- lgWidthPercentage?: number
- xlWidthPercentage?: number
- maxWidth?: number
- vimeoOptions?: any
- className?: string
id (required)
A unique id that is passed to the div which vimeo will use to load the player into.
- example value:
"product-introduction-video"
link (required)
The URL to your video hosted on vimeo (both private and public videos are supported as long as your domain is whitelisted).
- example value:
"https://vimeo.com/:id"
or"https://vimeo.com/:account/:id"
progressInterval (optional)
How often do you want the callback function onProgress
to be called?
- default is 10 seconds
- example value:
10000
// 10000ms === 10 seconds
onProgress (optional)
The callback function which will be fired every progressInterveral milliseconds.
Example implementation:
const handleProgress = useCallback((progress: number) => {
console.log(`The user has watched ${progress}% of the video!`);
});
Note, onProgress
is also called when the user pauses the video and when the video ends.
onPause (optional)
Will be called once when the user pauses the video. Use onProgress
to track progress. onPause
is handy to conditionally render something when the user pauses the video.
onVideoEnded (optional)
Will be called once when the user pauses the video. Use onProgress
to track progress. onVideoEnded
is handy to conditionally render something when the video ends.
widthPercentage (optional)
The default widthPercentage the vimeo player should take on the screen.
- default is 90%
- example value:
0.6
(for 60% of the screen size)
smWidthPercentage (optional)
Width percentage for small screens (takes over default).
Be aware that 0
will be treated as a falsy value and the default width will be used instead.
If you want to hide this player for a certain width, you have to do it yourself!
- default is
undefined
(widthPercentage is used) - example value:
0.9
(for 90% of the screen size)
mdWidthPercentage (optional)
Width percentage for medium-sized screens (takes over default)
Be aware that 0
will be treated as a falsy value and the default width will be used instead.
If you want to hide this player for a certain width, you have to do it yourself!
- default is
undefined
(widthPercentage is used) - example value:
0.7
(for 70% of the screen size)
lgWidthPercentage (optional)
Width percentage for large screens (takes over default)
Be aware that 0
will be treated as a falsy value and the default width will be used instead.
If you want to hide this player for a certain width, you have to do it yourself!
- default is
undefined
(widthPercentage is used) - example value:
0.6
(for 60% of the screen size)
xlWidthPercentage (optional)
Width percentage for extra large screens (takes over default)
Be aware that 0
will be treated as a falsy value and the default width will be used instead.
If you want to hide this player for a certain width, you have to do it yourself!
- default is
undefined
(widthPercentage is used) - example value:
0.5
(for 50% of the screen size)
maxWidth (optional)
A maximum width that the player should not exceed.
- default is none
- example value:
1200
(the player will not exceed 1200px)
vimeoOptions (optional)
The vimeo player takes an options property which allows further configuration.
Find the documentation here: embed options.
Please be aware that this object is typed as any
since vimeo does not officially support TypeScript and the current @types are outdated 😢.
I hope in the future, I can type this as Options
and also expose the Options
interface from the vimeo package.
className (optional)
A string of classes you want to pass on.
If you don't know how the className
property works, find more information here.