Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Frontend Modules

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

import { Property, PropertyList, ExpandableSection } from "@wix/docs-ui/content";

# Video

A video from Wix Media, carried at runtime as an object that bundles every playable source
so a player can choose the right one. Use it for a field that shows a video the Wix user picks
from the Media Manager, such as a promo clip or a background loop. The value holds both
progressive sources grouped by quality level and adaptive streaming sources, plus an
optional poster.

## Component

In your component code, import the `Video` type from `@wix/editor-react-types`:

```ts
import type { Video } from '@wix/editor-react-types';
```

A `Video` has the following properties:

<PropertyList bordered>
  <Property name="uri" type="string" required>
    The original video URI, such as `'wix:video://v1/def456.mp4'`.
  </Property>
  <Property
    name="sources"
    type="VideoSource[]"
    required
    description="Quality-level sources for progressive playback."
  >
    <ExpandableSection name="VideoSource properties">
      <PropertyList>
        <Property name="quality" type="'1080p' | '720p' | '480p' | '360p'" required description="The quality level." />
        <Property name="width" type="number" required description="The video width in pixels at this quality level." />
        <Property name="height" type="number" required description="The video height in pixels at this quality level." />
        <Property name="types" type="VideoSourceType[]" required description="The available file types for this quality level.">
          <ExpandableSection name="VideoSourceType properties">
            <PropertyList>
              <Property name="format" type="'mp4' | 'mp4-luminance'" required description="The video format." />
              <Property name="uri" type="string" required description="The video URI." />
              <Property name="url" type="string" required description="The fully resolved video URL." />
            </PropertyList>
          </ExpandableSection>
        </Property>
      </PropertyList>
    </ExpandableSection>
  </Property>
  <Property
    name="adaptiveSources"
    type="AdaptiveVideoSource[]"
    required
    description="Adaptive streaming sources, HLS or DASH."
  >
    <ExpandableSection name="AdaptiveVideoSource properties">
      <PropertyList>
        <Property name="format" type="'hls' | 'dash'" required description="The adaptive streaming format." />
        <Property name="uri" type="string" required description="The video URI." />
        <Property name="url" type="string" required description="The fully resolved video URL." />
      </PropertyList>
    </ExpandableSection>
  </Property>
  <Property
    name="hasAudio"
    type="boolean"
    required
    description="Whether the video contains an audio track."
  />
  <Property
    name="fps"
    type="number"
    required
    description="The video frame rate in frames per second."
  />
  <Property name="poster" type="Image">
    A poster image to display before the video plays, an
    [Image](fallback::https://dev.wix.com/docs/site-extensions/editor-react-components/editor-react-types/reference/image).
  </Property>
</PropertyList>

### Usage

Your code either consumes a value of type `Video` or produces one:

::::tabs
:::Consumers
In a component that receives a `Video`, pick a source URL and render it in a video
element:

```tsx
import type { Video } from '@wix/editor-react-types';

function Promo({ promoVideo }: { promoVideo?: Video }) {
  const src = promoVideo?.sources[0]?.types[0]?.url;
  return <video src={src} poster={promoVideo?.poster?.url} muted={!promoVideo?.hasAudio} />;
}
```
:::
:::Producers
When your code produces a `Video`, for a context or a function return, set `uri`,
the playable `sources`, `adaptiveSources`, `hasAudio`, and `fps`, and optionally a
`poster`:

```ts
import type { Video } from '@wix/editor-react-types';

const promoVideo: Video = {
  uri: 'wix:video://v1/def456.mp4',
  sources: [
    {
      quality: '1080p',
      width: 1920,
      height: 1080,
      types: [
        {
          format: 'mp4',
          uri: 'wix:video://v1/def456_1080p.mp4',
          url: 'https://video.wixstatic.com/video/def456/1080p/mp4/file.mp4',
        },
      ],
    },
  ],
  adaptiveSources: [],
  hasAudio: true,
  fps: 30,
  poster: {
    uri: 'wix:image://v1/poster123.jpg',
    url: 'https://static.wixstatic.com/media/poster123.jpg',
  },
};
```
:::
::::

## Manifest

In your manifest, declare the field with the `video` dataType:

```json
{ "dataType": "video" }
```

### Declaration

Declare a `video` field in one of these ways, depending on where the value comes from:

::::tabs
:::Data-property
Declare it as a data property when the Wix user should pick the `promoVideo` in a panel. It
takes `dataType`, `displayName`, an optional `defaultValue`, and the options that follow:

```json
{
  "promoVideo": {
    "dataType": "video",
    "displayName": "Promo Video",
    "defaultValue": {
      "uri": "wix:video://v1/def456.mp4",
      "hasAudio": true,
      "fps": 30,
      "sources": [
        {
          "quality": "1080p",
          "width": 1920,
          "height": 1080,
          "types": [{ "format": "mp4", "uri": "wix:video://v1/def456_1080p.mp4" }]
        }
      ],
      "poster": {
        "uri": "wix:image://v1/poster123.jpg"
      }
    },
    "video": {
      "category": "VIDEO_OPAQUE"
    }
  }
}
```

> **Your `defaultValue` sets media references, not the full object.** It provides a `uri`
> for the video and each source. Before your component runs, the editor resolves each `uri`
> into the complete `Video` object it receives, including the `url` on every source. Do not
> set `url` in your manifest.

#### Options

A `video` data property accepts the following options:

<PropertyList bordered>
  <Property
    name="category"
    type="string"
    description="Sets which Media Manager category the user picks the video from. Omit it to leave the category unspecified."
  >
    <ExpandableSection name="category values">
      <PropertyList>
        <Property name="'VIDEO_OPAQUE'" description="Videos without transparency." />
      </PropertyList>
    </ExpandableSection>
  </Property>
</PropertyList>
:::
:::Context-item
Declare it as a context item when your component supplies the video to descendant
components. It takes just `dataType` and `displayName`:

```json
{
  "promoVideo": {
    "dataType": "video",
    "displayName": "Promo Video"
  }
}
```
:::
:::Function-parameter-and-return
Declare it on a function when the function accepts or returns a video. It takes
`dataType` and an optional `displayName`, and a parameter may also set `optional`:

```json
{
  "parameters": [
    {
      "dataType": "video",
      "displayName": "Promo Video"
    }
  ],
  "returns": {
    "dataType": "video"
  }
}
```
:::
::::