Skip to main content

​
Prerequisites

Before installing Soundcn, ensure your project meets these requirements:
1

React 18+

Soundcn requires React 18 or higher for the useSound hook.
{
  "dependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  }
}
2

TypeScript (Recommended)

While not strictly required, TypeScript provides full type safety and IntelliSense for sound assets and options.
{
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}
3

Path Aliases

Configure path aliases in your tsconfig.json to use @/ imports:
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
Most modern React frameworks (Next.js, Vite, etc.) come with this configuration by default.

​
Installation Methods

​
Method 1: Install Individual Sounds

The recommended way to use Soundcn is to install individual sounds as needed:
1

Browse the Sound Library

Visit soundcn.xyz to browse and preview the 700+ available sounds. Use filters to find sounds by category, duration, or search terms.
2

Copy Installation Command

Click on any sound to view its details, then copy the installation command:
npx shadcn add https://soundcn.xyz/r/click-soft.json
This command will:
  • Install the sound file in src/sounds/click-soft/
  • Install the useSound hook in src/hooks/
  • Install supporting utilities in src/lib/
3

Run the Command

Execute the command in your project root:
npx shadcn add https://soundcn.xyz/r/click-soft.json
The shadcn CLI will prompt you to confirm the installation and show which files will be created.
The first time you install a sound, the CLI will also install the necessary dependencies (useSound hook, type definitions, and the sound engine).

​
Method 2: Install the Hook Only

If you want to set up the infrastructure without installing specific sounds: 
npx shadcn add https://soundcn.xyz/r/use-sound.json
This installs:
  • src/hooks/use-sound.ts - React hook for sound playback
  • src/lib/sound-engine.ts - Core Web Audio API utilities
  • src/lib/sound-types.ts - TypeScript type definitions

​
What Gets Installed

When you install a sound, the following files are added to your project:

​
Sound File

src/sounds/click-soft/
└── click-soft.ts
Contains the sound asset with embedded base64 audio data: 
import type { SoundAsset } from "@/lib/sound-types";

export const clickSoftSound: SoundAsset = {
  name: "click-soft",
  dataUri: "data:audio/mpeg;base64,...",
  duration: 0.007,
  format: "mp3",
  license: "CC0",
  author: "Kenney",
};

​
useSound Hook

src/hooks/
└── use-sound.ts
A React hook for playing sounds with full control: 
export function useSound(
  sound: SoundAsset,
  options?: UseSoundOptions
): UseSoundReturn;

​
Sound Engine

src/lib/
├── sound-engine.ts
├── sound-types.ts
Core utilities for audio playback using the Web Audio API, including:
  • Audio context management
  • Audio buffer caching
  • Base64 decoding and audio data processing
  • Framework-agnostic playSound() function

​
Verify Installation

After installation, verify the files were created: 
ls -la src/sounds/click-soft/
ls -la src/hooks/
ls -la src/lib/sound-*.ts

​
Project Structure

After installing several sounds, your project structure will look like: 
src/
├── hooks/
│   └── use-sound.ts           # React hook
├── lib/
│   ├── sound-engine.ts        # Web Audio API utilities
│   └── sound-types.ts         # TypeScript types
└── sounds/
    ├── click-soft/
    │   └── click-soft.ts      # Sound asset
    ├── notification-pop/
    │   └── notification-pop.ts
    └── transition-whoosh/
        └── transition-whoosh.ts

​
Installing Multiple Sounds

You can install multiple sounds in sequence: 
npx shadcn add https://soundcn.xyz/r/click-soft.json
npx shadcn add https://soundcn.xyz/r/notification-pop.json
npx shadcn add https://soundcn.xyz/r/transition-whoosh.json
The hook and library files are only installed once. Subsequent sound installations only add the new sound files.

​
Framework-Specific Notes

​
Next.js

Soundcn works with both the App Router and Pages Router:
  • App Router: Mark components using useSound with "use client" directive
  • Pages Router: Works out of the box
  • Server Components: Use the playSound() function in client components
"use client";

import { useSound } from "@/hooks/use-sound";
import { clickSoftSound } from "@/sounds/click-soft";

export function ClientButton() {
  const [play] = useSound(clickSoftSound);
  return <button onClick={play}>Click me</button>;
}

​
Vite

Works seamlessly with Vite’s default React setup. Ensure path aliases are configured in vite.config.ts: 
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
});

​
Create React App

Configure path aliases using craco or react-app-rewired. Alternatively, use relative imports: 
import { useSound } from "../../hooks/use-sound";
import { clickSoftSound } from "../../sounds/click-soft";

​
Troubleshooting

This usually means path aliases aren’t configured. Check your tsconfig.json:
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
For Vite, also configure vite.config.ts (see Framework-Specific Notes above).
Mobile browsers require user interaction before playing audio. Ensure the first sound is triggered by a user action (click, tap):
const [play] = useSound(clickSoftSound);

// ✅ Triggered by user action
<button onClick={play}>Play</button>

// ❌ Autoplay won't work on mobile
useEffect(() => play(), []);
Make sure TypeScript can find the type definitions:
import type { SoundAsset } from "@/lib/sound-types";
If errors persist, restart your TypeScript server in VS Code:
  • Cmd/Ctrl + Shift + P
  • “TypeScript: Restart TS Server”
The shadcn CLI should work with npx without installation. If it fails:
npm install -g shadcn@latest
shadcn add https://soundcn.xyz/r/click-soft.json

​
Next Steps

Now that Soundcn is installed:

Build docs developers (and LLMs) love

Get started for freeTalk to us