# 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.

> **Tip: Coming from another player?**
>
> Follow the React migration guide for [Video.js 8](https://deploy-preview-9472--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-video-js-8), [Mux Player](https://deploy-preview-9472--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-mux-player), [Plyr](https://deploy-preview-9472--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-plyr), [Media Chrome](https://deploy-preview-9472--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-media-chrome), [Vidstack](https://deploy-preview-9472--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-vidstack), or [Video-React](https://deploy-preview-9472--vjs10-site.netlify.app/docs/framework/react/guides/migrate-from-video-react). 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. Neutral has cleaner surfaces and the same controls as Default. Values: `default`, `neutral`, `compat`, `scaffold`. 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. In a workspace with several apps, choose the app the request names and run the command from its directory, since detection reads the package.json where it runs. When the request does not identify one app, ask: "Which app should get the player: \<app> or \<app>?" Without an answer, choose the app that serves the page the request describes and report that choice.
2. **Check for Video.js 8.** The `video.js` package, `class="video-js"`, `data-setup`, or a `videojs(...)` call means existing pages run Video.js 8. Build new players with Video.js 10, which uses separate `@videojs/*` packages, and leave existing Video.js 8 players unchanged. Migrate one only when the user asks, following the Migrate from Video.js 8 guide instead of this plan. When the request could mean replacing an existing player, ask: "Should I migrate the existing Video.js 8 player, or add a Video.js 10 player and leave it as it is?" Without an answer, add the Video.js 10 player. Tell the user the project now uses both versions and that the Video.js 8 players can be migrated later.
3. **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. When the workspace and request do not make it clear, ask: "Should I add the player to the existing app or create a new one?" Without an answer, use existing when an app exists.
4. **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.
5. **Choose the skin.** Use default unless the request asks for a minimal, cleaner, or more subtle look, which uses neutral; both contain the same controls. Ask only when those signals conflict.
6. **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.
7. **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.
8. **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.
9. **Choose the styling.** For React, use tailwind in a new app or an existing Tailwind app; otherwise use css. HTML source uses css.
10. **Return one explicit plan.** Put any questions from the steps above in one message, each with the default you would otherwise use, and ask nothing when the signals agree. When you cannot ask, use those defaults and report each one with the result. 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://deploy-preview-9472--vjs10-site.netlify.app/docs/guides/installation/react.md)
- [Packaged modules: HTML](https://deploy-preview-9472--vjs10-site.netlify.app/docs/guides/installation/html.md)
- [Packaged modules: Vue](https://deploy-preview-9472--vjs10-site.netlify.app/docs/guides/installation/vue.md)
- [Packaged modules: Svelte](https://deploy-preview-9472--vjs10-site.netlify.app/docs/guides/installation/svelte.md)
- [Editable Shadcn source: React source](https://deploy-preview-9472--vjs10-site.netlify.app/docs/guides/installation/shadcn.md?framework=react)
- [Editable Shadcn source: HTML source](https://deploy-preview-9472--vjs10-site.netlify.app/docs/guides/installation/shadcn.md?framework=html)
- [CDN: HTML from jsDelivr](https://deploy-preview-9472--vjs10-site.netlify.app/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://deploy-preview-9472--vjs10-site.netlify.app/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://deploy-preview-9472--vjs10-site.netlify.app/docs/framework/react/guides/customize-skins#style-skin-source): Change the installed layout, controls, styles, and interactions
- [UI components](https://deploy-preview-9472--vjs10-site.netlify.app/docs/framework/react/guides/architecture#ui-components): Explore the building blocks used by skins and custom controls
- [Build your own component](https://deploy-preview-9472--vjs10-site.netlify.app/docs/framework/react/guides/build-your-own-component): Connect custom UI to player state and actions

#### Deploy

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

---

React documentation: https://deploy-preview-9472--vjs10-site.netlify.app/docs/framework/react/llms.txt
HTML documentation: https://deploy-preview-9472--vjs10-site.netlify.app/docs/framework/html/llms.txt
All documentation: https://deploy-preview-9472--vjs10-site.netlify.app/llms.txt
