Setup

The components are distributed as a shadcn registry. Add them with the CLI, and the source is copied into your project.

Prerequisites

A React project with Tailwind CSS. The components ship a little Tailwind for layout. Replace it with your own CSS if you prefer.
A BeyondWords project ID and a source ID (or content ID) for the audio you want to play. The examples below use a public demo project.

You don’t need to install @beyondwords/player yourself. It’s listed as a dependency of the components, so the CLI adds it for you.

Add a component

Add the Play Pause Button. No configuration is needed. The CLI resolves its dependencies automatically, so this also pulls in Player Provider and New Event, plus the @beyondwords/player package.

npx @beyondwords/cli components add play-pause-button

If your project has a components.json, the CLI delegates the install to shadcn, so your aliases and styles config are respected. Without one, it copies the files to components/beyondwords/ (it asks first). Adjust the @/registry/react/ import paths in these docs to wherever the files landed.

Build your first player

Wrap your UI in PlayerProvider. It mounts the player and shares the instance with everything inside it. Pass the player config through args, and set showUserInterface: false to hide the player’s built-in UI so yours is the only one on the page.

app.tsx

import { PlayerProvider } from '@/registry/react/PlayerProvider';
import { PlayPauseButton } from '@/registry/react/PlayPauseButton';

export function App() {
  return (
    <PlayerProvider args={{ projectId: 9504, contentId: 'ba00ef51-03ac-4a85-8b98-e45c957e8ef8', showUserInterface: false }}>
      <PlayPauseButton />
    </PlayerProvider>
  );
}

Every component reads what it needs from the surrounding provider, so adding controls is just composition. Drop a Progress Bar and a Time Indicator into a flex row:

app.tsx

import { PlayerProvider } from '@/registry/react/PlayerProvider';
import { PlayPauseButton } from '@/registry/react/PlayPauseButton';
import { ProgressBar } from '@/registry/react/ProgressBar';
import { TimeIndicator } from '@/registry/react/TimeIndicator';

export function App() {
  return (
    <PlayerProvider args={{ projectId: 9504, contentId: 'ba00ef51-03ac-4a85-8b98-e45c957e8ef8', showUserInterface: false }}>
      <div className="flex items-center gap-3">
        <PlayPauseButton />
        <ProgressBar />
        <TimeIndicator />
      </div>
    </PlayerProvider>
  );
}

That’s a working player. It looks plain because the components are minimal by design; Theming shows how to make it yours. To start from something finished instead, the Standard Player example assembles all of these controls into a polished layout. It wraps its own provider, so you only pass projectId and contentId:

Using the shadcn CLI instead (optional)

The registry also works with the shadcn CLI directly. Add components by full URL:

npx shadcn add https://ui.beyondwords.io/r/react/play-pause-button.json

Or register the registry namespace once in your components.json, then use short names:

components.json

{
  "registries": {
    "@beyondwords-react": "https://ui.beyondwords.io/r/react/{name}.json"
  }
}

npx shadcn add @beyondwords-react/play-pause-button

Next steps

Theming

Style the components to match your brand.

Player Provider

Read player state and drive playback.

Examples

Start from a complete, pre-built player.

Troubleshooting

Fix common setup issues.

Getting started

Components

Examples

Prerequisites

Add a component

Build your first player

Using the shadcn CLI instead (optional)

Next steps

Theming

Player Provider

Examples

Troubleshooting

​Prerequisites

​Add a component

​Build your first player

​Using the shadcn CLI instead (optional)

​Next steps

Theming

Player Provider

Examples

Troubleshooting

Prerequisites

Add a component

Build your first player

Using the shadcn CLI instead (optional)

Next steps