---
title: "기본 사용법"
slug: "vpe-react-getting-started"
updated: 2026-09-17T09:08:03Z
published: 2026-09-17T09:08:03Z
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.

# 기본 사용법

Classic/VPC 환경에서 이용 가능합니다.

React/Next.js 환경에서 VPE 플레이어를 사용하는 방법을 설명합니다.

## React/Next.js

`VpePlayer` 컴포넌트를 import하고 필수 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: "영상 제목",
                profile_name: "채널명",
              },
            },
          ],
          autostart: true,
          muted: true,
          aspectRatio: "16/9",
        }}
      />
    </div>
  );
}
```

### 필수 Props

| Prop | 타입 | 설명 |
| --- | --- | --- |
| `hls` | `typeof Hls` | hls.js 모듈 (HLS 재생 시 필수) |
| `accessKey` | `string` | 네이버 클라우드 플랫폼 Access Key |
| `options` | `PlayerOptions` | 플레이어 옵션 객체 |

### 선택 Props

| Prop | 타입 | 설명 |
| --- | --- | --- |
| `ref` | `Ref&lt;PlayerHandle&gt;` | 플레이어 제어 핸들 (메서드 호출용) |
| `dashjs` | `typeof dashjs` | dashjs 모듈 (DASH 재생 시) |
| `layout` | `LayoutConfig` | 커스텀 레이아웃 설정 |
| `platform` | `string` | 플랫폼 구분 (`"pub"` 등) |

## 레이아웃 커스텀

`layout` prop으로 플레이어 UI를 커스터마이징할 수 있습니다. 레이아웃은 `pc`, `mobile`, `fullscreen` 환경별로 독립 정의됩니다.

```
{
  "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" }
      ]
    }
  }
}
```

레이아웃 JSON은 [UI Editor](https://vpe-player-editor.web.app/)에서 시각적으로 편집할 수도 있습니다.