---
title: VideoPlayer
description: Video.js-powered player with automatic format handling.
source_url:
  html: 'https://shopify.dev/docs/api/shop-minis/components/primitives/videoplayer'
  md: 'https://shopify.dev/docs/api/shop-minis/components/primitives/videoplayer.md'
api_name: shop-minis
---

# VideoPlayer

Video.js-powered player with automatic format handling. Includes custom play/pause overlay and imperative controls via ref (for advanced scenarios like synchronized playback). Video.js handles codec support, adaptive streaming, and disposal lifecycle automatically.

#### Props

* **src**

  **string**

  **required**

  The video source URL

* **autoplay**

  **boolean**

  Whether the video should autoplay

* **format**

  **string**

  The format/MIME type of the video (default: 'video/mp4')

* **height**

  **number**

  Video height in pixels

* **loop**

  **boolean**

  Whether the video should loop

* **muted**

  **boolean**

  Whether the video should be muted

* **onEnded**

  **() => void**

  Callback when video ends

* **onPause**

  **() => void**

  Callback when video is paused

* **onPlay**

  **() => void**

  Callback when video starts playing

* **onReady**

  **() => void**

  Callback when video player is ready

* **playButtonComponent**

  **React.ReactNode**

  Custom play button component

* **poster**

  **string**

  URL for the poster image shown before playback

* **preload**

  **'none' | 'metadata' | 'auto'**

  Preload behavior: 'none', 'metadata', or 'auto'

* **width**

  **number**

  Video width in pixels

Examples

## Preview

![videoplayer](https://shopify.dev/assets/assets/images/templated-apis-screenshots/shop-minis/VideoPlayer-5jH-I4pB.png)

### Examples

* ####

  ##### tsx

  ```tsx
  import React from 'react'

  import {VideoPlayer} from '@shopify/shop-minis-react'

  export default function MyComponent() {
    return (
      <VideoPlayer
        src="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
        poster="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/images/BigBuckBunny.jpg"
        width={320}
        muted
      />
    )
  }
  ```

* ####

  ##### Description

  A basic video player with a fixed height and poster image

  ##### tsx

  ```tsx
  import React from 'react'

  import {VideoPlayer} from '@shopify/shop-minis-react'

  export default function MyComponent() {
    return (
      <VideoPlayer
        src="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
        poster="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/images/BigBuckBunny.jpg"
        width={320}
        muted
      />
    )
  }
  ```

* ####

  ##### Description

  Video player with imperative controls

  ##### tsx

  ```tsx
  import {useRef} from 'react'
  import {VideoPlayer, Button, VideoPlayerRef} from '@shopify/shop-minis-react'

  export default function MyComponent() {
    const handlePlay = () => {
      ref.current?.play()
    }

    const handlePause = () => {
      ref.current?.pause()
    }

    const ref = useRef<VideoPlayerRef>(null)

    return (
      <div>
        <VideoPlayer
          ref={ref}
          src="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
          width={400}
          height={225}
        />
        <div style={{marginTop: '10px', display: 'flex', gap: '10px'}}>
          <Button onClick={handlePlay}>Play</Button>
          <Button onClick={handlePause} variant="secondary">
            Pause
          </Button>
        </div>
      </div>
    )
  }
  ```

***