---
title: "Basic usage"
slug: "vpe-react-getting-started"
updated: 2026-09-17T09:22:36Z
published: 2026-09-17T09:22:36Z
canonical: "guide.ncloud-docs.com/vpe-react-getting-started"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Basic usage

Available in Classic and VPC

This guide explains how to use the VPE player in React and Next.js.

## React/Next.js

Import the `VpePlayer` component and pass the required props.

`app/player/page.tsx`

```
"use client";
import Hls from "hls.js";
import { VpePlayer, type PlayerHandle } from "@sgrsoft/vpe-react-sdk";
import { useRef } from "react";

export default function PlayerPage() {
  const playerRef = useRef<PlayerHandle>(null);

  return (
    <div style={{ maxWidth: "800px", margin: "0 auto" }}>
      <VpePlayer
        ref={playerRef}
        hls={Hls}
        accessKey="YOUR_ACCESS_KEY"
        options={{
          playlist: [
            {
              file: "https://example.com/video/master.m3u8",
              poster: "https://example.com/poster.jpg",
              description: {
                title: "Video title",
                profile_name: "Channel name",
              },
            },
          ],
          autostart: true,
          muted: true,
          aspectRatio: "16/9",
        }}
      />
    </div>
  );
}
```

### Required props

| Prop | Type | Description |
| --- | --- | --- |
| `hls` | `typeof Hls` | hls.js module (required for HLS playback) |
| `accessKey` | `string` | NAVER Cloud Platform access key |
| `options` | `PlayerOptions` | Player option object |

### Choose props

| Prop | Type | Description |
| --- | --- | --- |
| `ref` | `Ref&lt;PlayerHandle&gt;` | Player control handle (for calling methods) |
| `dashjs` | `typeof dashjs` | dashjs module (for DASH playback) |
| `layout` | `LayoutConfig` | Custom layout settings |
| `platform` | `string` | Platform identifier (e.g., `&quot;pub&quot;`) |

## Layout custom

You can customize the player UI with the `layout` prop. You can define layouts independently for `pc`, `mobile`, and `fullscreen` environments.

```
{
  "pc": {
    "vod": {
      "order": ["top", "upper", "center", "lower", "bottom"],
      "top": [
        { "items": ["MetaDesc"] },
        { "wrapper": "Blank", "items": [], "align": "left" },
        { "items": ["ShareBtn"] }
      ],
      "center": [
        { "items": ["BigPlayBtn"], "align": "center" }
      ],
      "bottom": [
        { "items": ["ProgressBar"] },
        { "items": ["PlayBtn", "VolumeBtn", "TimeDisplay"], "align": "left" },
        { "items": ["SettingBtn", "PIPBtn", "FullscreenBtn"], "align": "right" }
      ]
    }
  }
}
```

You can also edit the layout JSON visually in the [UI editor](https://vpe-player-editor.web.app/).