Installation

Step 1: Install one componentCopy Anchor Link

Start with just a button. There is no reason to install all 24 components before you need them:

npx shadcn@latest add SatyamVyas04/sensory-ui/sensory-ui-button

This pulls the core engine (provider, config, all 9 sound packs) plus the Button. The registry is served directly from the public GitHub repository via registry.json. No custom registry server or URL required.

Step 2: Choose a sound packCopy Anchor Link

sensory-ui ships with 9 sound packs. The default is aero (clean, modern SaaS: filtered tones, balanced):

Pass it to the provider: config={{ theme: "arcade" }} (or keep a theme field in your own sensory.config.js and spread it into the provider; see Configuration). All packs share the same roles, so switching is a one-line theme change.

Step 3: Check the filesCopy Anchor Link

With the Button install, only button.tsx lands alongside the core. Other components appear as you add them:

Audio is generated programmatically via the Web Audio API inside sensory-ui/sounds/. No files in public/, no asset serving, no base64 blobs. sensory.config.js is an optional user-owned convention: if you create one at the project root, spread it into the provider (<SensoryUIProvider config={config}>); deleting it simply falls back to the built-in defaults.

Step 4: Wrap the app in SensoryUIProviderCopy Anchor Link

The provider must wrap the entire component tree so the AudioContext persists across navigations and all components have access to playSound.

// app/layout.tsx
import { SensoryUIProvider } from "@/components/ui/sensory-ui/config/provider";
import type { ReactNode } from "react";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <SensoryUIProvider>{children}</SensoryUIProvider>
      </body>
    </html>
  );
}

Step 5: Use a sound-enabled componentCopy Anchor Link

Import any component directly from sensory-ui and pass a sound prop:

import { Button } from "@/components/ui/sensory-ui/button";

export function SaveButton() {
  return (
    <Button sound="interaction.tap" onClick={handleSave}>
      Save
    </Button>
  );
}

The sound prop is the only required change from standard shadcn/ui usage. All other props, variants, and behaviour are identical.

Step 6: Verify installationCopy Anchor Link

Open the browser devtools console and look for any sensory-ui warnings. In development mode, the engine logs a warning if a sound cannot be resolved.

Validate the GitHub registry payload from the CLI:

npx shadcn@latest registry validate SatyamVyas04/sensory-ui
npx shadcn@latest list SatyamVyas04/sensory-ui

Or build locally to validate:

bun run registry:build

Temporarily set volume: 1.0 in your provider config and click a Button with sound="interaction.tap". You should hear the tap sound.

If you hear nothing:

1. Check that SensoryUIProvider wraps the component you are testing
2. Check that the config has enabled: true
3. Check that the sound modules were installed correctly (open components/ui/sensory-ui/sounds/packs.ts and verify it exports sound pack objects)
4. Check that the click is a direct user gesture (not triggered on mount)
5. Check that your browser has not blocked the AudioContext. Chrome suspends it until a user gesture. The engine resumes it automatically on the first playSound() call.