Theming - Docs and guides

The components are deliberately minimal and unopinionated. There’s no theme prop and no set of CSS variables to override. Because the CLI copies the source into your project, you own the code, so styling means editing it: change its classes, swap its icons, restructure its markup. Nothing is hidden behind a package boundary. This page shows the patterns. The Minimal Player example below is a full worked walkthrough.

Where the styles live

After you add a component, its source sits in your project (by default under @/registry/react/). Open the file and you’ll find ordinary JSX with a default inline SVG icon and, where needed, a little Tailwind. For example, the Play Pause Button renders a bare button with the default play / pause icon:

PlayPauseButton.tsx

<button onClick={/* emits PressedPlay / PressedPause */}>
  {isPlaying ? <svg>{/* default pause icon */}</svg> : <svg>{/* default play icon */}</svg>}
</button>

Edit the classes in place

To theme it, add the classes you want and swap the icons for your own. For example, restyle the same component into a round brand-purple button:

PlayPauseButton.tsx

<button
  className="flex size-12 items-center justify-center rounded-full bg-[#943bfc] text-white cursor-pointer hover:opacity-90"
  onClick={/* emits PressedPlay / PressedPause */}
>
  {playbackState === 'playing' ? <PauseIcon /> : <PlayIcon />}
</button>

Use your own design tokens instead of arbitrary values (bg-[#943bfc]) wherever you can, such as bg-brand or bg-primary from your Tailwind theme. This keeps the player in sync with the rest of your app.

Swap the icons

Each component ships a default inline SVG icon (the same art the real BeyondWords player uses). It’s just markup in the file you own, so replace it with your own SVG, an icon library, or text. The button reads playbackState, so you decide what each state renders:

{isPlaying ? (
  <svg>{/* your pause icon */}</svg>
) : (
  <svg>{/* your play icon */}</svg>
)}

The icons use fill="currentColor", so by default they take the surrounding text color. Set a color on the button (or the icon) to change them.

Conditional classes with `cn`

For state-dependent styling, the cn helper (installed at @/lib/utils) merges class lists and resolves Tailwind conflicts. The examples use it to restyle themselves when they detach into a floating widget:

import { cn } from '@/lib/utils';

<div
  className={cn(
    'flex h-12 items-center gap-2 rounded-3xl bg-[#F5F5F5] p-1',
    mode === 'widget' && 'fixed right-4 bottom-4 z-50 shadow-md',
  )}
>

Dark mode

There’s no dark-mode toggle baked in. Use Tailwind’s dark: variant so the player follows your app’s existing color scheme:

<div className="bg-white text-black dark:bg-zinc-900 dark:text-white">

Primitives vs. examples

Components (primitives) are minimal and unopinionated on purpose. The Progress Bar, for instance, ships just enough Tailwind to be usable: a translucent track with a solid fill. Override those classes freely.
Examples are fully styled, pre-assembled players. Read them as worked references, or copy one and restyle it rather than starting from scratch.

Worked example: Minimal Player

The Minimal example takes the same components shown throughout these docs and restyles and recomposes them into a clean “listen to article” strip in the style of news-site players: a transparent single-line bar with no background pill. While stopped it shows only a play button and the call to action; once playback starts it swaps in a skip-back 10s control, a 0.9x–2x speed menu, and the current time. Nothing about the player engine changed. Only the classes, icons and layout did. Use it as a template. Copy it, restyle it to match your brand, and you have a custom player without touching playback, analytics, ads or segments.

​Where the styles live

​Edit the classes in place

​Swap the icons

​Conditional classes with cn

​Dark mode

​Primitives vs. examples

​Worked example: Minimal Player