Skip to content


Repository files navigation


JavaScript API to generate a blurry image placeholder for a Mux video.

The library retrieves a tiny video poster image from the Mux API and generates a blurry image placeholder by upscaling the image and applying a Gaussian blur.

See the blog post for more information:


npm install @mux/blurup

Usage (Demo)

import { createBlurUp } from '@mux/blurup';

const options = {};
const muxPlaybackId = 'O6LdRc0112FEJXH00bGsN9Q31yu5EIVHTgjTKRkKtEq1k';

const { blurDataURL, aspectRatio } = await createBlurUp(muxPlaybackId, options);
console.log(blurDataURL, aspectRatio);
// data:image/svg+xml;charset=utf-8,<svg xmlns="" width="100%" ...


Parameter Type Description Default
time number The video timestamp from which to grab the blurhash. (If you're using a thumbnailToken, then the time option will have no effect; encode time in your token according to the secure video playback guide linked below) undefined
width string Width of the output blurry image placeholder. 100%
height string Height of the output blurry image placeholder. 100%
blur number Standard deviation of the Gaussian blur. 20
quality number Quality of the output image. Increase this value to see more details but also increase the length of the data URL. 1
thumbnailToken string Videos with playback restrictions may require a thumbnail token. See for details. undefined
type webp png jpg Image type to use in the output blurry image placeholder. webp

Using blurDataURL with Mux Player

Be sure to escape the double quotes in the blurDataURL string when using it in an HTML attribute.

mux-player element

<mux-player placeholder="{blurDataURL}" style="aspect-ratio: {aspectRatio}"></mux-player>

mux-player element with slotted poster (Demo)

<mux-player style="aspect-ratio: {aspectRatio}">
      width: 100%;
      background-size: cover;
      background-position: center;
      background-repeat: no-repeat;
      background-image: url("{blurDataURL}");

mux-player-react and mux-player-react/lazy

<MuxPlayer placeholder={blurDataURL} style={{ aspectRatio }} />

Using blurDataURL with native elements

Be sure to escape the double quotes in the blurDataURL string when using it in an HTML attribute.


<img src="{blurDataURL}" width="300" style="aspect-ratio: {aspectRatio}" />


background-image: url('{blurDataURL}');
aspect-ratio: {aspectRatio};