# Shadcn Installation Guide

Add editable React or HTML skin source with the Shadcn registry

Use Shadcn to add a Video.js skin's components, layout, styles, and interactions as React or HTML custom-element source. The CLI copies the files into your app so you can review and change them like any other source code.

> **Note: Release Candidate**
>
> Video.js v10 is a *release candidate*. We feel the API is stable and ready to build with. With your [feedback](https://github.com/videojs/v10/issues), a few documentation updates, and any final fixes, we look forward to shipping 10.0.0 soon. [Read the Release Candidate blog post](https://videojs.org/blog/videojs-v10-release-candidate).

> **Tip: Coming from another player?**
>
> Follow the React migration guide for [Video.js 8](https://videojs.org/docs/framework/react/guides/migrate-from-video-js-8), [Mux Player](https://videojs.org/docs/framework/react/guides/migrate-from-mux-player), [Plyr](https://videojs.org/docs/framework/react/guides/migrate-from-plyr), or [Media Chrome](https://videojs.org/docs/framework/react/guides/migrate-from-media-chrome). Each maps your existing setup onto Video.js v10 instead of starting from scratch.

## AI Quickstart

Paste this prompt into your coding agent:

```
Install the Video.js skill: run `npx @videojs/cli agents skills` and follow the steps for the agent you are running in. If you can't run commands, follow the install instructions at https://github.com/videojs/skills instead. Then use the Video.js skill when you work on video or audio in this project. When installation details are needed, run `npx @videojs/cli agents init --method shadcn --framework react` for React, or `npx @videojs/cli agents init --method shadcn --framework html` for plain HTML. The command prints version-matched choices and instructions without changing files.
```

## Installation options for coding agents

The web Markdown page contains the default installation. Add the query parameters below to its `.md` URL for a complete, validated variation. From a project or an offline docs bundle, run the CLI command below instead. Both paths use the same installation renderer and only return instructions; they do not modify a project.

This page fixes the installation method to `shadcn`. The `framework` query parameter selects React or HTML.

```sh
npx @videojs/cli agents init
```

### Query parameters

- `framework`: The application framework that will host the player. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html. Values: `react`, `html`. Default: react.
- `project`: Whether to adapt the current project or scaffold a new one. New projects need a named app setup. Values: `new`, `existing`. Default: existing.
- `preset`: The player configuration and control set. Values: `video`, `audio`, `live-video`, `live-audio`. Default: video.
- `skin`: The visual skin. Minimal has cleaner surfaces and the same controls as Default. Values: `default`, `minimal`. Default: default. Applies when preset is not background-video.
- `media`: The media source or playback adapter. See the preset compatibility map below. Values: `background-video`, `hls-background-video`, `cloudflare`, `dash`, `hls`, `html5-audio`, `html5-video`, `mux-audio`, `mux-background-video`, `mux-video`, `spotify`, `tiktok`, `twitch`, `vimeo`, `youtube`. Default: the selected preset's first compatible media source.
- `extensions`: A comma-separated list of optional player extensions compatible with the selected player. Pass `none` when no extension is needed. Values: `none`, `google-cast`, `mux-data`. Default: mux-data for Mux media; none otherwise (reported as defaulted).
- `source-url`: The http:// or https:// media URL placed in the generated player example. Pass `demo` to choose the Video.js demo source for the selected media explicitly. Default: the Video.js demo source for the selected media (reported as defaulted).
- `package-manager`: The command runner used for app setup, packages, Shadcn, and the development server. Values: `npm`, `pnpm`, `yarn`, `bun`. Default: pnpm. Applies when method is not cdn with template none.
- `template`: The app setup and file layout. Values: `next`, `vite`, `start`, `react-router`, `astro`, `laravel`. Default: next for React; vite otherwise.
- `styling`: The Shadcn source styling. Compatible values depend on the framework. Values: `tailwind`, `css`. Default: tailwind for React; css otherwise. Applies when method=shadcn.

Run the command above without flags to see the corresponding CLI flags for every framework.

### Decide in this order

1. **Inspect the project.** Read package.json, framework config, and lockfiles to infer the framework, app setup, and package manager. React installs @videojs/react; HTML, Vue, and Svelte install @videojs/html.
2. **Choose the starting point.** Use existing when adapting a compatible project. Use new only when the user wants a new app or the intended workspace has no app. Confirm the choice when the workspace and request do not make it clear.
3. **Choose the player.** Use video unless the request signals another experience: audio, music, or podcasts use audio; a live stream uses live-video or live-audio; a muted, looping decorative video uses background-video. Ask only when those signals conflict.
4. **Choose the skin.** Use default unless the request asks for a minimal, cleaner, or more subtle look, which uses minimal; both contain the same controls. Ask only when those signals conflict.
5. **Choose the media.** Infer the adapter from the source when possible. Mux wins for Mux playback URLs: stream.mux.com/\<playback-id>.m3u8 or a bare playback ID uses mux-video, mux-audio, or mux-background-video rather than hls. Mux static renditions such as .mp4 or .m4a files use html5-video or html5-audio. Other .m3u8 URLs use hls.
6. **Choose extensions.** Mux Data is included by default for Mux video and audio sources. Add Google Cast when a standard or live video player with a ready-made skin should cast a compatible source. Use none when no extension is needed.
7. **Choose how to install.** This guide uses Shadcn to copy editable skin source. React uses the React source catalog; plain HTML uses the HTML source catalog. Vue and Svelte use packaged modules.
8. **Choose the styling.** For React, use tailwind in a new app or an existing Tailwind app; otherwise use css. HTML source uses css.
9. **Return one explicit plan.** Confirm the choices once, then pass every applicable query parameter, including `extensions=none` when no extension is needed and `source-url=demo` when there is no media URL yet. Check that Defaulted options says none. Adapt conditional setup steps and existing paths before changing files.

### Compatible media sources by preset

- `video`: `html5-video`, `hls`, `dash`, `mux-video`, `vimeo`, `youtube`, `cloudflare`, `tiktok`, `twitch`
- `audio`: `html5-audio`, `mux-audio`, `spotify`
- `live-video`: `hls`, `mux-video`
- `live-audio`: `mux-audio`

### App setup and Shadcn styling by framework

- `react`: templates `next`, `vite`, `start`, `react-router`, `astro`, `laravel`; styling `tailwind`, `css`
- `html`: templates `vite`, `astro`, `laravel`; styling `css`

### Installation pages

- [Packaged modules: React](https://videojs.org/docs/guides/installation/react.md)
- [Packaged modules: HTML](https://videojs.org/docs/guides/installation/html.md)
- [Packaged modules: Vue](https://videojs.org/docs/guides/installation/vue.md)
- [Packaged modules: Svelte](https://videojs.org/docs/guides/installation/svelte.md)
- [Editable Shadcn source: React source](https://videojs.org/docs/guides/installation/shadcn.md?framework=react)
- [Editable Shadcn source: HTML source](https://videojs.org/docs/guides/installation/shadcn.md?framework=html)
- [CDN: HTML from jsDelivr](https://videojs.org/docs/guides/installation/cdn.md)

## Selected options

- `method`: `shadcn`
- `framework`: `react`
- `project`: `existing`
- `preset`: `video`
- `skin`: `default`
- `media`: `html5-video`
- `extensions`: `none`
- `source-url`: `https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4`
- `package-manager`: `pnpm`
- `template`: `next`
- `styling`: `tailwind`

Defaulted options: project, preset, skin, source-url, media, extensions, template, package-manager, styling.

## Reproduce or change these instructions

```sh
npx @videojs/cli agents init --method shadcn --framework react --project existing --preset video --skin default --media html5-video --extensions none --source-url https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4 --package-manager pnpm --template next --styling tailwind
```

## Create components.json

_Only when components.json is missing._

The registry steps below need components.json, so create it when the project has none. `shadcn init` also rewrites the theme tokens in the global stylesheet, such as app/globals.css or src/index.css; review that diff and restore any project tokens that should stay.

```bash
pnpm dlx shadcn@latest init --base base --preset nova --yes
```

## Add the Video.js Registry

This adds the selected @videojs catalog when the namespace is missing. If components.json already defines @videojs with another URL, replace that value with the URL from this command first because Shadcn skips configured namespaces.

```bash
pnpm dlx shadcn@latest registry add @videojs=https://shadcn.videojs.org/r/react/{name}.json
```

## Add the skin source

Make sure the working tree is clean or checkpointed so every added or replaced file is reviewable; ask before committing. The add command overwrites an existing Video.js skin so catalog and theme changes fully apply. Review and remove obsolete Video.js style files left by a previous catalog.

```bash
pnpm dlx shadcn@latest add @videojs/video --overwrite --yes
```

## Add your player

Use the aliases.components value from components.json in the skin import when it differs from the generated @/components path. Merge the example into the existing Next.js route or component that should render the player, and preserve unrelated content.

### `app/page.tsx`

_Merge this into the existing file, or create the file when it is missing._

```tsx
import { VideoPlayer, Video } from '@videojs/react/video';
import { VideoSkin } from '@/components/videojs/video/skin';

export default function Page() {
  return (
    <VideoPlayer>
      <VideoSkin className="aspect-video w-full">
        <Video src={"https://stream.mux.com/BV3YZtogl89mg9VcNBhhnHm02Y34zI1nlMuMQfAbl3dM/highest.mp4"} playsInline />
      </VideoSkin>
    </VideoPlayer>
  );
}
```

## Run your app

Start the development server and verify that the selected media plays.

_Long-running: start it in the background, verify the result, then stop it._

```bash
pnpm dev
```

> These are instructions only. Review and run the commands in your project; no files were modified. Shadcn copies the current Video.js registry source, while package installs use the version shown above.

That’s it! You now have a working Video.js player whose skin source lives in your project.

## Change the skin source

### React

Start in `<components alias>/videojs/<preset>/skin.tsx`. Follow the [Customize skins](https://videojs.org/docs/framework/react/guides/customize-skins#style-skin-source) guide for the files that control layout, colors, controls, and interactions.

## Choose what to do next

### React

#### Customize

- [Customize skin source](https://videojs.org/docs/framework/react/guides/customize-skins#style-skin-source): Change the installed layout, controls, styles, and interactions
- [UI components](https://videojs.org/docs/framework/react/guides/architecture#ui-components): Explore the building blocks used by skins and custom controls
- [Build your own component](https://videojs.org/docs/framework/react/guides/build-your-own-component): Connect custom UI to player state and actions

#### Deploy

- [Browser support](https://videojs.org/docs/framework/react/guides/browser-support): Check supported browsers and rendering environments
- [TypeScript](https://videojs.org/docs/framework/react/guides/typescript): Configure TypeScript for Video.js packages
- [Bundlers](https://videojs.org/docs/framework/react/guides/bundlers): Check bundler compatibility
- [Content Security Policy](https://videojs.org/docs/framework/react/guides/content-security-policy): Configure Content Security Policy for your player

---

React documentation: https://videojs.org/docs/framework/react/llms.txt
HTML documentation: https://videojs.org/docs/framework/html/llms.txt
All documentation: https://videojs.org/llms.txt