---
name: "NativeVideo"
mode: "component"
versionRequirements:
  - { name: "@ray-js/ray", version: "0.6.9" }
title: "NativeVideo - Video"
---

## NativeVideo

> [VERSION] @ray-js/ray >= 0.6.9

### Description

Native video playback component.

### Props

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `src` | `string` | Yes | - | URL of the video to play; network URLs are supported. In partitioned deployments, ensure the video is accessible |
| `duration` | `number` | No | - | Specify the video duration, in seconds |
| `controls` | `boolean` | No | `true` | Whether to show the default controls (play/pause button, progress, time) |
| `autoplay` | `boolean` | No | `false` | Whether to autoplay |
| `loop` | `boolean` | No | `false` | Whether to loop |
| `muted` | `boolean` | No | `false` | Whether to mute |
| `initialTime` | `number` | No | `0` | Initial playback position |
| `showFullscreenBtn` | `boolean` | No | `true` | Whether to show the fullscreen button |
| `showPlayBtn` | `boolean` | No | `true` | Whether to show the play button in the bottom control bar |
| `showCenterPlayBtn` | `boolean` | No | `true` | Whether to show the center play button |
| `objectFit` | `"contain" \| "fill" \| "cover" \| "none"` | No | `"contain"` | How the video is fitted when its size differs from the video container |
| `poster` | `string` | No | - | Poster image URL |
| `showMuteBtn` | `boolean` | No | `false` | Whether to show the mute button |
| `borderWidth` | `number` | No | `0` | Border width, in px |
| `borderStyle` | `"solid" \| "dashed"` | No | `"solid"` | Border style; valid values: solid, dashed |
| `borderColor` | `string` | No | `"#ffffff"` | Border color, must be hex format |
| `borderRadius` | `number` | No | `0` | Border radius, in px |
| `borderRadiusTopLeft` | `number` | No | - | Top-left border radius, in px |
| `borderRadiusTopRight` | `number` | No | - | Top-right border radius, in px |
| `borderRadiusBottomLeft` | `number` | No | - | Bottom-left border radius, in px |
| `borderRadiusBottomRight` | `number` | No | - | Bottom-right border radius, in px |
| `backgroundColor` | `string` | No | `"#ffffff"` | Background color, must be hex format |
| `onPlay` | `() => void` | No | - | Triggers when playback starts or resumes |
| `onPause` | `() => void` | No | - | Triggers when playback is paused |
| `onEnded` | `() => void` | No | - | Triggers when playback reaches the end |
| `onTimeupdate` | `(event: NativeVideoTimeUpdateEvent) => void` | No | - | Triggers when the playback position changes |
| `onFullscreenchange` | `(event: NativeVideoFullscreenChangeEvent) => void` | No | - | Triggers when entering or exiting fullscreen |
| `onWaiting` | `() => void` | No | - | Triggers when buffering occurs |
| `onError` | `(event: NativeVideoErrorEvent) => void` | No | - | Triggers on playback error |
| `onProgress` | `(event: NativeVideoProgressEvent) => void` | No | - | Triggers when load progress changes; only a single segment is supported |
| `onLoadedmetadata` | `(event: NativeVideoLoadedMetadataEvent) => void` | No | - | Triggers when video metadata has loaded |
| `onControlstoggle` | `(event: NativeVideoControlsToggleEvent) => void` | No | - | Triggers when controls visibility toggles |
| `onSeekcomplete` | `(event: NativeVideoSeekCompleteEvent) => void` | No | - | Triggers when seek completes |
| `updateLayout` | `unknown` | No | - | Used for cross-layer components to notify the container layer to update styles |

### Referenced Types

##### `interface` NativeVideoTimeUpdateEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `NativeVideoTimeUpdateDetail` | Event data |

##### `interface` NativeVideoFullscreenChangeEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `NativeVideoFullscreenChangeDetail` | Event data |

##### `interface` NativeVideoErrorEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `NativeVideoErrorDetail` | Event data |

##### `interface` NativeVideoProgressEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `NativeVideoProgressDetail` | Event data |

##### `interface` NativeVideoLoadedMetadataEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `NativeVideoLoadedMetadataDetail` | Event data |

##### `interface` NativeVideoControlsToggleEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `NativeVideoControlsToggleDetail` | Event data |

##### `interface` NativeVideoSeekCompleteEvent

| Property | Type | Description |
| --- | --- | --- |
| `detail` | `NativeVideoSeekCompleteDetail` | Event data |

##### `interface` NativeVideoTimeUpdateDetail

| Property | Type | Description |
| --- | --- | --- |
| `currentTime` | `number` | Current playback progress (seconds) |
| `duration` | `number` | Total video duration (seconds) |

##### `interface` BaseEvent

| Property | Type | Description |
| --- | --- | --- |
| `type` | `string` | Event type |
| `timeStamp` | `number` | Time in milliseconds since the page opened |
| `target` | `Target` | Source component of the event |
| `currentTarget` | `Target` | Collection of property values for the current component |
| `mark` | `any` | Event mark data |

##### `interface` NativeVideoFullscreenChangeDetail

| Property | Type | Description |
| --- | --- | --- |
| `fullScreen` | `boolean` | Whether fullscreen |
| `direction` | `"vertical" \| "horizontal"` | Direction; valid values are vertical or horizontal |

##### `interface` NativeVideoErrorDetail

| Property | Type | Description |
| --- | --- | --- |
| `errMsg` | `string` | Error message |

##### `interface` NativeVideoProgressDetail

| Property | Type | Description |
| --- | --- | --- |
| `buffered` | `number` | Buffering percentage |

##### `interface` NativeVideoLoadedMetadataDetail

| Property | Type | Description |
| --- | --- | --- |
| `width` | `number` | Video width |
| `height` | `number` | Video height |
| `duration` | `number` | Video duration |

##### `interface` NativeVideoControlsToggleDetail

| Property | Type | Description |
| --- | --- | --- |
| `show` | `boolean` | Whether to show controls |

##### `interface` NativeVideoSeekCompleteDetail

| Property | Type | Description |
| --- | --- | --- |
| `position` | `number` | Playback position after seek |

##### `interface` Target

| Property | Type | Description |
| --- | --- | --- |
| `id` | `string` | id of the event source component |
| `dataset` | `Record<string, unknown>` | Collection of custom attributes from the `dataset` on the event source component |


### Examples

#### Basic usage

```tsx
import React from 'react';
import { NativeVideo, View } from '@ray-js/ray';

export default function () {
  return (
    <View style={{ padding: '20px' }}>
      <NativeVideo
        src="https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-95db-cfd3b8132c07-1778036702734.mp4"
        controls
        style={{ width: '100%', height: '200px' }}
        onPlay={() => console.log('Playback started')}
        onPause={() => console.log('Playback paused')}
        onEnded={() => console.log('Playback ended')}
      />
    </View>
  );
}
```

#### Playback configuration and cover

```tsx
import React from 'react';
import { NativeVideo, View } from '@ray-js/ray';

export default function () {
  return (
    <View style={{ padding: '20px' }}>
      <NativeVideo
        src="https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-95db-cfd3b8132c07-1778036702734.mp4"
        poster="https://vjs.zencdn.net/v/oceans.png"
        controls
        autoplay={false}
        loop
        muted
        initialTime={3}
        objectFit="cover"
        showFullscreenBtn
        showPlayBtn
        showCenterPlayBtn={false}
        showMuteBtn
        style={{ width: '100%', height: '200px' }}
        onError={(e) => console.log('Playback error:', e.detail.errMsg)}
        onWaiting={() => console.log('Buffering')}
        onTimeupdate={(e) => console.log('Progress:', e.detail.currentTime, '/', e.detail.duration)}
      />
    </View>
  );
}
```

#### Custom border and events

```tsx
import React from 'react';
import { NativeVideo, View } from '@ray-js/ray';

export default function () {
  return (
    <View style={{ padding: '20px' }}>
      <NativeVideo
        src="https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-95db-cfd3b8132c07-1778036702734.mp4"
        controls
        borderWidth={2}
        borderStyle="dashed"
        borderColor="#1890ff"
        borderRadius={16}
        backgroundColor="#000000"
        style={{ width: '100%', height: '200px' }}
        onPlay={() => console.log('Play')}
        onPause={() => console.log('Pause')}
        onEnded={() => console.log('Ended')}
        onFullscreenchange={(e) => console.log('Fullscreen:', e.detail.fullScreen, 'Direction:', e.detail.direction)}
        onControlstoggle={(e) => console.log('Controls visible:', e.detail.show)}
        onProgress={(e) => console.log('Buffered:', e.detail.buffered + '%')}
        onLoadedmetadata={(e) => console.log('Metadata:', e.detail.width, 'x', e.detail.height)}
        onSeekcomplete={(e) => console.log('seek:', e.detail.position)}
      />
    </View>
  );
}
```


### Related Links

Related API: [createNativeVideoContext](/en/miniapp/develop/miniapp/api/media/native-video/createNativeVideoContext). This is a native component based on off-screen rendering. Please note the [native component usage restrictions](/en/miniapp/develop/miniapp/component/native-component/native-component).

<DemoBlock 
  githubUrl="https://github.com/Tuya-Community/tuya-miniapp-demo/tree/master/rayVideo" 
  qrCodeUrl="/images/qrCode/rayVideo.png" 
  lang="en">
</DemoBlock>

### FAQ

1. `native-video` default width is 300px and height is 225px. You can set the width and height via tyss.
2. For related principles, refer to [Native components based on off-screen rendering](/en/miniapp/develop/miniapp/component/native-component/native-component).
3. Please note the [native component usage restrictions](/en/miniapp/develop/miniapp/component/native-component/native-component).
4. Supported video format for `native-video`: MP4 (MPEG-4 files using H.264 video codec and AAC audio codec).