A super lightweight component and HLS engine for creating background videos using Mux HLS streams.
- Background Video: Perfect for hero sections, landing pages, and immersive experiences
- HLS Video Support: Built-in HLS video engine for smooth streaming
- React: React component for easy integration
- Web Components: Custom element for easy integration
- TypeScript Support: Full TypeScript definitions included
- Lightweight: Minimal bundle size with no dependencies
- Preload Control: Control video preloading behavior
- Audio Control: Optionally enable audio tracks for background videos
- Resolution Control: Set maximum resolution for optimal performance
npm install mux-embed # Enable Mux Data integration
npm install @mux/mux-background-videoImportant
Requires Mux Basic or Premium video quality currently because transmuxing of .ts segments is not supported.
The easiest way to use Mux Background Video is with the custom element:
<!DOCTYPE html>
<html>
<head>
<title>Background Video</title>
<style>
html,
body {
height: 100%;
}
body {
margin: 0;
padding: 0;
}
mux-background-video,
img {
display: block;
width: 100%;
height: 100%;
object-fit: cover;
}
</style>
<!-- (optional) Enable Mux Data integration -->
<script defer src="https://cdn.jsdelivr.net/npm/mux-embed"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/@mux/mux-background-video/html/+esm"></script>
</head>
<body>
<mux-background-video src="https://stream.mux.com/YOUR_PLAYBACK_ID.m3u8">
<img src="https://image.mux.com/YOUR_PLAYBACK_ID/thumbnail.webp?time=0" alt="Mux Background Video" />
</mux-background-video>
</body>
</html>You can also import the custom element directly:
import 'mux-embed'; // (optional) Enable Mux Data integration
import '@mux/mux-background-video/html';
// The custom element is automatically registered
// You can now use <mux-background-video> in your HTMLFor React applications, use the React component:
import 'mux-embed'; // (optional) Enable Mux Data integration
import { MuxBackgroundVideo } from '@mux/mux-background-video/react';
function HeroSection() {
return (
<MuxBackgroundVideo src="https://stream.mux.com/YOUR_PLAYBACK_ID.m3u8">
<img src="https://image.mux.com/YOUR_PLAYBACK_ID/thumbnail.webp?time=0" alt="Mux Background Video" />
</MuxBackgroundVideo>
);
}Mux data integrates with video players to provide detailed analytics and insights about video performance, which can be found in the Mux dashboard. Mux can also use this performance data to help improve the player and streaming. All that's required to use Mux data is including or importing the script. Once the script is included, Mux data will automatically be enabled for all background videos on the page.
<script defer src="https://cdn.jsdelivr.net/npm/mux-embed"></script>The <mux-background-video> element automatically handles HLS streaming.
src: The Mux HLS stream URL (required)max-resolution: Maximum resolution for the video (e.g., "720p", "1080p")audio: Enable audio track (default: false)preload: Controls video preloading behavior (default: auto)"none": No preloading"metadata": Preload only metadata"auto": Preload video data
<mux-background-video audio max-resolution="720p" src="YOUR_STREAM_URL">
<img src="https://image.mux.com/YOUR_PLAYBACK_ID/thumbnail.webp?time=0" alt="Mux Background Video" />
</mux-background-video>You can also set attributes programmatically:
const element = document.querySelector('mux-background-video');
// Set maximum resolution
element.setAttribute('max-resolution', '1080p');
// Enable audio track
element.toggleAttribute('audio', true);
// Set preload behavior
element.setAttribute('preload', 'metadata');
// Set the stream URL
element.setAttribute('src', 'https://stream.mux.com/NEW_PLAYBACK_ID.m3u8');
// Get current values
console.log(element.getAttribute('src'));
console.log(element.getAttribute('max-resolution'));
console.log(element.hasAttribute('audio'));
console.log(element.getAttribute('preload'));src: The Mux HLS stream URL (required)maxResolution: Maximum resolution for the video (e.g., "720p", "1080p")audio: Enable audio track (default: false)preload: Controls video preloading behavior (default: auto)"none": No preloading"metadata": Preload only metadata"auto": Preload video data
<MuxBackgroundVideo
src="https://stream.mux.com/YOUR_PLAYBACK_ID.m3u8"
maxResolution="720p"
audio={true}
>
<img src="https://image.mux.com/YOUR_PLAYBACK_ID/thumbnail.webp?time=0" alt="Mux Background Video" />
</MuxBackgroundVideo>- Node.js 18+
- npm or yarn
- Clone the repository:
git clone <repository-url>
cd mux-background-video- Install dependencies:
npm install- Start the development server:
npm startnpm start: Start development server with watch modenpm run build: Build the projectnpm run watch: Watch for changes and rebuildnpm test: Run tests locallynpm run test:browserstack: Run integration tests on BrowserStacknpm run setup:browserstack: Interactive setup for BrowserStack credentials
Run tests locally:
npm testWhen running the dev server, you can use the following URL parameters:
PLAYBACK_ID: Set a custom Mux playback ID (defaults to demo video)max-resolution: Set maximum resolution for the background videoaudio: Enable or disable audio track (default: false)preload: Set preload behavior ("none", "metadata", or "auto")debug: Enable debug modenomuted: Disable muted attributenoloop: Disable loop attributenoautoplay: Disable autoplay attribute
Example:
http://localhost:3000/PLAYBACK_ID?max-resolution=720p&audio=1&preload=metadata
MIT License - see LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.
For issues and questions, please open an issue on GitHub.