- [`` component for easy video integration.](#videoplayer-component-for-easy-video-integration)
- [Out-of-the-box features](#out-of-the-box-features)
- [Installation](#installation)
- [Usage](#usage)
- [Example](#example)
- [Props](#props)
- [Advanced usage: the `useVideoPlayer` hook](#advanced-usage-the-usevideoplayer-hook)
- [Example](#example-1)
- [Opt-in Viewer Analytics](#opt-in-viewer-analytics)
# `` component for easy video integration.
`` is a React component specially designed to work seamlessly with DatoCMS’s [`video` GraphQL query](https://www.datocms.com/docs/content-delivery-api/images-and-videos#videos) that optimizes video streaming for your sites.
To stream videos, DatoCMS partners with MUX, a video CDN that serves optimized streams to your users. Our component is a wrapper over MUX's video player for React. It takes care of the details for you, and this is our recommended way to serve optimal videos to your users.
## Out-of-the-box features
- Offers optimized streaming so smartphones and tablets don’t request desktop-sized videos
- Lazy loads the video component and the video to be played to speed initial page load and save bandwidth
- Holds the video position and size so your page doesn’t jump while the player loads
- Uses blur-up technique to show a placeholder of the video while it loads
## Installation
```
npm install --save react-datocms @mux/mux-player-react
```
`@mux/mux-player-react` is a [peer dependency](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#peerdependencies) for `react-datocms`: so you're expected to add it in your project.
## Usage
1. Import `VideoPlayer` from `react-datocms` and use it in your app
2. Write a GraphQL query to your DatoCMS project using the [`video` query](https://www.datocms.com/docs/content-delivery-api/images-and-videos#videos)
The GraphQL query returns data that the `VideoPlayer` component automatically uses to properly size the player, set up a “blur-up” placeholder as well as lazy loading the video.
## Example
For a fully working example take a look at our [examples directory](https://github.com/datocms/react-datocms/tree/master/examples).
```js
import React from 'react';
import { VideoPlayer } from 'react-datocms';
const Page = ({ data }) => (
{data.blogPost.title}
);
const query = gql`
query {
blogPost {
title
cover {
video {
# required: this field identifies the video to be played
muxPlaybackId
# all the other fields are not required but:
# if provided, title is displayed in the upper left corner of the video
title
# if provided, width and height are used to define the aspect ratio of the
# player, so to avoid layout jumps during the rendering.
width
height
# if provided, it shows a blurred placeholder for the video
blurUpThumb
# if provided, it enables DatoCMS Content Link for click-to-edit overlays
alt
# you can include more data here: they will be ignored by the component
}
}
}
}
`;
export default withQuery(query)(Page);
```
## Props
The `` components supports all [the properties made
available](https://github.com/muxinc/elements/blob/main/packages/mux-player-react/REFERENCE.md)
for `` component from `@mux/mux-player-react` package plus `data`,
which is meant to receive data directly in the shape they are provided by
DatoCMS GraphQL API.
`` uses the `data` prop to generate a set of props for the inner
``. On this topic, also see the "Advanced usage" section below.
| prop | type | required | description | default |
| ---- | -------------- | ------------------ | ---------------------------------------------------------------- | ------- |
| data | `Video` object | :white_check_mark: | The actual response you get from a DatoCMS `video` GraphQL query | |
Compared to the ``, **some prop default values are different** on ``
- `disableCookies` is normally true, unless you explicitly set the prop to `false`
- `disableTracking` is normally true, unless you explicitly set it to `false`
- `preload` defaults to `metadata`, for an optimal UX experience together with saved bandwidth
- the video height and width, when available in the `data` props, are used to set `{ aspectRatio: "[width] / [height]"}` for the ``'s `style`
All the other props are forwarded to the `` component that is used internally.
## Advanced usage: the `useVideoPlayer` hook
Even though we try our best to make the `` suitable and easy to use for most normal use cases, there are situations where you may need to leverage the `` directly (let's suppose you wrote your special wrapper component around the `` and you need a bunch of props to pass). If that's the case, fill free to use the hook we provide: `useVideoPlayer`.
`useVideoPlayer` takes data coming in the shape they are produced from DatoCMS API and return props that you can pass to the `` component. That's pretty much what the `` does internally.
### Example
```
import { useVideoPlayer } from 'react-datocms';
const data = {
muxPlaybackId: 'ip028MAXF026dU900bKiyNDttjonw7A1dFY',
title: 'Title',
width: 1080,
height: 1920,
blurUpThumb:
'data:image/bmp;base64,Qk0eAAAAAAAAABoAAAAMAAAAAQABAAEAGAAAAP8A',
};
// `props` is the following object:
//
// {
// playbackId: 'ip028MAXF026dU900bKiyNDttjonw7A1dFY',
// title: 'Title',
// style: {
// aspectRatio: '1080 / 1920',
// },
// placeholder:
// 'data:image/bmp;base64,Qk0eAAAAAAAAABoAAAAMAAAAAQABAAEAGAAAAP8A',
// }
const props = useVideoPlayer({ data });
```
## Opt-in Viewer Analytics
This `` component can OPTIONALLY collect clientside [playback and engagement metrics](https://www.mux.com/data#TechSpecs) such as playback percentages, user agents, and geography.
These analytics are **disabled** by default. To enable them, you must opt in to [Mux Data](https://www.mux.com/data) integration by creating a Mux Data account (free) and providing its `envKey` to the component.
For details and setup instructions, please see our documentation on **[Streaming Video Analytics with Mux Data](https://www.datocms.com/docs/streaming-videos/streaming-video-analytics-with-mux-data)**.