---
name: "native-video"
mode: "component"
versionRequirements:
  - { name: "Base Library", version: "2.10.0" }
title: "native-video - Video"
---

## native-video

> [VERSION] Base Library >= 2.10.0

### Description

Native video player component; the rendering layer is implemented by the client and supported only in native environments

### Props

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `hidden` | `boolean` | No | - | Whether to hide the component. |
| `src` | `string` | No | - | Video source URL. |
| `poster` | `string` | No | - | Video cover image URL |
| `controls` | `boolean` | No | - | Whether to show default playback controls. |
| `duration` | `number` | No | `0` | Specify video duration |
| `autoplay` | `boolean` | No | - | Whether to autoplay |
| `loop` | `boolean` | No | - | Whether to loop |
| `muted` | `boolean` | No | - | Whether to play muted |
| `initial-time` | `number` | No | `0` | Specifies the initial playback position, in seconds. |
| `object-fit` | `string` | No | `"contain"` | Video fit mode; options: contain, fill, cover |
| `show-fullscreen-btn` | `boolean` | No | - | Whether to show the fullscreen button |
| `show-play-btn` | `boolean` | No | - | Whether to show the play button. |
| `show-mute-btn` | `boolean` | No | - | Whether to show the mute button |
| `show-center-play-btn` | `boolean` | No | - | Whether to show the play button in the center of the video |
| `auto-pause` | `boolean` | No | - | Whether to auto-pause the video on this page when navigating to another page |
| `background-color` | `string` | No | `"#ffffff"` | Background color, must be a hex color value |
| `border-width` | `number` | No | `0` | Border width, in px |
| `border-style` | `string` | No | `"solid"` | Border style |
| `border-color` | `string` | No | `"#ffffff"` | Border color, must be a hex color value |
| `border-radius` | `number` | No | `0` | Set a unified corner radius for all four corners, in px |
| `border-radius-top-left` | `number` | No | - | Top-left corner radius, in px; -1 indicates using border-radius |
| `border-radius-top-right` | `number` | No | - | Top-right corner radius, in px; -1 indicates using border-radius |
| `border-radius-bottom-left` | `number` | No | - | Bottom-left corner radius, in px; -1 indicates using border-radius |
| `border-radius-bottom-right` | `number` | No | - | Bottom-right corner radius, in px; -1 indicates using border-radius |

#### Events

| Event | Type | Description |
| --- | --- | --- |
| `play` | `(event: Object) => void` | Fires when playback starts or resumes |
| `pause` | `(event: Object) => void` | Triggered when playback is paused |
| `ended` | `(event: Object) => void` | Triggered when playback ends |
| `timeupdate` | `(event: NativeVideoTimeupdateEvent) => void` | Triggered when the playback progress changes |
| `fullscreenchange` | `(event: NativeVideoFullscreenchangeEvent) => void` | Triggered when the video enters or exits full screen |
| `waiting` | `(event: Object) => void` | Triggered when buffering occurs |
| `error` | `(event: NativeVideoErrorEvent) => void` | Triggered when a playback error occurs |
| `progress` | `(event: NativeVideoProgressEvent) => void` | Fires when loading progress changes |
| `loadedmetadata` | `(event: NativeVideoLoadedmetadataEvent) => void` | Triggered when video metadata is loaded |
| `controlstoggle` | `(event: NativeVideoControlstoggleEvent) => void` | Triggered when toggling the visibility of controls |
| `seekcomplete` | `(event: NativeVideoSeekcompleteEvent) => void` | Triggered when seek completes |

**play callback object**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"play"` |  |

**pause callback object**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"pause"` |  |

**ended callback object**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"ended"` |  |

**NativeVideoTimeupdateEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"timeupdate"` | Event type |
| `detail` | `NativeVideoTimeupdateDetail` | Event data |

**NativeVideoFullscreenchangeEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"fullscreenchange"` | Event type |
| `detail` | `NativeVideoFullscreenchangeDetail` | Event data |

**waiting callback object**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"waiting"` |  |

**NativeVideoErrorEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"error"` | Event type |
| `detail` | `NativeVideoErrorDetail` | Event data |

**NativeVideoProgressEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"progress"` | Event type |
| `detail` | `NativeVideoProgressDetail` | Event data |

**NativeVideoLoadedmetadataEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"loadedmetadata"` | Event type |
| `detail` | `NativeVideoLoadedmetadataDetail` | Event data |

**NativeVideoControlstoggleEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"controlstoggle"` | Event type |
| `detail` | `NativeVideoControlstoggleDetail` | Event data |

**NativeVideoSeekcompleteEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"seekcomplete"` | Event type |
| `detail` | `NativeVideoSeekcompleteDetail` | Event data |

### Examples

#### Basic usage

*index.tyml*

```xml
<native-video
  src="{{videoSrc}}"
  controls="{{true}}"
  class="video"
  bindplay="onPlay"
  bindpause="onPause"
  bindended="onEnded"
/>
```

*index.tyss*

```css
.video {
  width: 100%;
  height: 400rpx;
}
```

*index.js*

```javascript
Page({
  data: {
    videoSrc: 'https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-95db-cfd3b8132c07-1778036702734.mp4',
  },
  onPlay() {
    console.log('Start playing');
  },
  onPause() {
    console.log('Paused');
  },
  onEnded() {
    console.log('Playback ended');
  },
});
```

#### Playback configuration and poster

*index.tyml*

```xml
<native-video
  src="{{videoSrc}}"
  poster="{{posterUrl}}"
  controls="{{true}}"
  autoplay="{{false}}"
  loop="{{true}}"
  muted="{{true}}"
  initial-time="{{3}}"
  object-fit="cover"
  show-fullscreen-btn="{{true}}"
  show-play-btn="{{true}}"
  show-center-play-btn="{{false}}"
  show-mute-btn="{{true}}"
  class="video"
  binderror="onError"
  bindwaiting="onWaiting"
/>
```

*index.tyss*

```css
.video {
  width: 100%;
  height: 400rpx;
}
```

*index.js*

```javascript
Page({
  data: {
    videoSrc: 'https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-95db-cfd3b8132c07-1778036702734.mp4',
    posterUrl: 'https://vjs.zencdn.net/v/oceans.png',
  },
  onError(e) {
    console.log('Playback error:', e.detail.errMsg);
  },
  onWaiting() {
    console.log('Buffering');
  },
});
```

#### Muted autoplay

*index.tyml*

```xml
<native-video
  src="{{videoSrc}}"
  autoplay="{{true}}"
  muted="{{true}}"
  loop="{{true}}"
  controls="{{false}}"
  show-center-play-btn="{{false}}"
  auto-pause="{{true}}"
  class="video"
/>
```

*index.tyss*

```css
.video {
  width: 100%;
  height: 400rpx;
  border-radius: 16rpx;
}
```

*index.js*

```javascript
Page({
  data: {
    videoSrc: 'https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-95db-cfd3b8132c07-1778036702734.mp4',
  },
});
```


### Related Documents

- Related API: [ty.createNativeVideoContext](/en/miniapp/develop/miniapp/api/media/native-video/createNativeVideoContext)
- This is a native component rendered based on heterolayers. Take care of the [limitations of the native component](/en/miniapp/develop/miniapp/component/native-component/native-component).

### FAQ

1. `native-video` has a default width of 300px and height of 225px. You can set the dimensions via tyss.
2. `native-video` supports the MP4 format (MPEG-4 files using H264 video codec and AAC audio codec).