Installation

Prerequisites

waves-cn components are plain shadcn/ui components. You need:

React 18 or newer
Tailwind CSS v4
shadcn/ui initialised in the project (components.json present)

If you have not set up shadcn/ui yet:

pnpm dlx shadcn@latest init

npx shadcn@latest init

yarn dlx shadcn@latest init

bunx --bun shadcn@latest init

1. Register the registry

The shadcn CLI only resolves @waves-cn/* names once the namespace is declared in your components.json. Do this once per project, either with the CLI:

pnpm dlx shadcn@latest registry add @waves-cn=https://waves-cn.vercel.app/r/{name}.json

npx shadcn@latest registry add @waves-cn=https://waves-cn.vercel.app/r/{name}.json

yarn dlx shadcn@latest registry add @waves-cn=https://waves-cn.vercel.app/r/{name}.json

bunx --bun shadcn@latest registry add @waves-cn=https://waves-cn.vercel.app/r/{name}.json

or by editing components.json by hand:

components.json

{
  "registries": {
    "@waves-cn": "https://waves-cn.vercel.app/r/{name}.json"
  }
}

2. Add a component

pnpm dlx shadcn@latest add @waves-cn/wave-player

npx shadcn@latest add @waves-cn/wave-player

yarn dlx shadcn@latest add @waves-cn/wave-player

bunx --bun shadcn@latest add @waves-cn/wave-player

The CLI installs:

the component at components/waves-cn/wave-player.tsx
the shared core at lib/wave-cn.tsx (WavesurferPlayer, useWavePlayer, useWavesurfer, formatTime, useCssVar)
the shadcn primitives it uses (button, card, slider, …) if they are not already in your project
the wavesurfer.js and lucide-react npm packages

Every component is listed on its docs page with the exact command. Replace wave-player with any of wave-recorder, wave-regions, wave-timeline, wave-minimap, wave-spectrogram, wave-speed, wave-zoom, wave-hover, wave-envelope, wave-video.

3. Use it

import WavePlayer from "@/components/waves-cn/wave-player";

export default function Page() {
  return <WavePlayer src="/track.mp3" title="My track" />;
}

Manual installation

Each component page has a Manual tab with the full source of the component and of lib/wave-cn.tsx. Copy both, then install the runtime dependencies:

npm install wavesurfer.js lucide-react

and make sure the shadcn primitives the component imports (button, card, slider, switch, label) exist under components/ui/.