React Modern Audio Player

Highlights

Waveform progress bar powered by wavesurfer.js
Playlist with drag-and-drop reorder, repeat, shuffle
Fully customizable — swap any sub-component, CSS variable theming, light & dark themes
Compound slots — AudioPlayer.Volume, AudioPlayer.Progress, AudioPlayer.PlayList, etc. for partial customization without losing the preset
Multi-instance playlist — render multiple players on the same page with isolated playlist drawers and fully independent audio state
Accessible — WAI-ARIA patterns, full keyboard navigation, axe-tested
TypeScript-first — typed props and hooks (useAudioPlayer, sub-hooks)
SSR-friendly — works with Next.js App Router / Server Components

DEMO

https://codesandbox.io/p/sandbox/basic-nfrpfq

or

https://stackblitz.com/edit/stackblitz-webcontainer-api-starter-k4uxhzjx?file=src%2FApp.tsx

Flexible and Customizable UI

Waveform progress with `wavesurfer.js`

Customizable layout and placement — with light & dark themes

Full View

Position Change

Particular View

Installation

npm install --save react-modern-audio-player

Requirements

React 18.0.0 or higher
react-dom 18.0.0 or higher

For React 16/17 projects, use v1.x of this library.

Quick Start

import AudioPlayer from "react-modern-audio-player";

const playList = [
  {
    name: "name",
    writer: "writer",
    img: "image.jpg",
    src: "audio.mp3",
    id: 1,
  },
];
function Player() {
  return <AudioPlayer playList={playList} />;
}

Next.js / Server Components

This library includes the 'use client' directive and can be imported directly in Next.js App Router.

Server Component — render <AudioPlayer> with static props (no hooks, no compound components):

// app/page.tsx — Server Component, no 'use client' needed
import AudioPlayer from "react-modern-audio-player";

const playList = [
  {
    name: "track",
    writer: "artist",
    img: "cover.jpg",
    src: "audio.mp3",
    id: 1,
  },
];

export default function Page() {
  return <AudioPlayer playList={playList} activeUI={{ playButton: true }} />;
}

Client Component — use useAudioPlayer hooks or AudioPlayer.CustomComponent:

"use client";
// app/player/page.tsx — Client Component required for hooks & compound pattern
import AudioPlayer, { useAudioPlayer } from "react-modern-audio-player";

function Controls() {
  const { isPlaying, togglePlay } = useAudioPlayer();
  return <button onClick={togglePlay}>{isPlaying ? "Pause" : "Play"}</button>;
}

export default function PlayerPage() {
  return (
    <AudioPlayer playList={playList}>
      <AudioPlayer.CustomComponent id="controls">
        <Controls />
      </AudioPlayer.CustomComponent>
    </AudioPlayer>
  );
}

Why 'use client'? The library's 'use client' directive marks the client boundary — it allows Server Components to import and render <AudioPlayer>. However, useAudioPlayer() hooks and AudioPlayer.CustomComponent require client-side React features (state, context), so components using them must be Client Components.

Category	Sections
Props	PlayList · InitialStates · ActiveUI · Placement · RootContainerProps
Override & Style	CustomIcons · CoverImgsCss · Theme mode · ID & Classnames
Player Hook API	useAudioPlayer · AudioPlayerControls · Sub-Hooks
Custom Component	Custom Component · Compound Slots
Accessibility	Keyboard support
Gotchas	Gotchas
Example	Example

Props

interface AudioPlayerProps {
  playList: PlayList;
  audioInitialState?: InitialStates;
  audioRef?: React.MutableRefObject<HTMLAudioElement>;
  activeUI?: ActiveUI;
  customIcons?: CustomIcons;
  coverImgsCss?: CoverImgsCss;
  placement?: {
    player?: PlayerPlacement;
    playList?: PlayListPlacement;
    interface?: InterfacePlacement;
    volumeSlider?: VolumeSliderPlacement;
    speedSelector?: SpeedSelectorPlacement;
  };
  rootContainerProps?: RootContainerProps;
  colorScheme?: "light" | "dark";
}

Prop	Type	Default
`playList`	PlayList	[ ]
`audioInitialState`	InitialStates	isPlaying: false repeatType: "ALL" volume: 1
`activeUI`	ActiveUI	playButton : true
`customIcons`	CustomIcons	undefined
`coverImgsCss`	CoverImgsCss	undefined
`placement`	Placement	playListPlacement : "bottom" interfacePlacement :DefaultInterfacePlacement
`rootContainerProps`	RootContainerProps	width: 100% position: 'static' className: rmap-player-provider
`colorScheme`	`"light" \| "dark"`	undefined (follows OS `prefers-color-scheme`)

PlayList

type PlayList = Array<AudioData>;
type AudioData = {
  src: string;
  id: number;
  name?: string;
  writer?: string;
  img?: string;
  description?: string | ReactNode;
  customTrackInfo?: string | ReactNode;
};

Empty playlist handling

Passing playList={[]} renders the player in an empty state without crashing. This is useful while waiting for asynchronous track data:

function App() {
  const [tracks, setTracks] = useState<PlayList>([]);

  useEffect(() => {
    fetchTracks().then(setTracks);
  }, []);

  // Safe — the player mounts with no audio source and activates once tracks arrive.
  return <AudioPlayer playList={tracks} />;
}

When the playlist becomes empty after updates, playback stops and all time state resets.
When audioInitialState.curPlayId doesn't match any track in the current list, the player falls back to playList[0] automatically.

InitialStates

type InitialStates = Omit<
  React.AudioHTMLAttributes<HTMLAudioElement>,
  "autoPlay"
> & {
  isPlaying?: boolean;
  repeatType?: RepeatType;
  volume?: number;
  currentTime?: number;
  duration?: number;
  curPlayId: number;
  playListExpanded?: boolean;
};

playListExpanded: true opens the playlist drawer on mount. Consistent with the other fields on audioInitialState, this is read once at mount and is not tracked in reducer state.

ActiveUI

type ActiveUI = {
  all: boolean;
  playButton: boolean;
  playList: PlayListUI;
  prevNnext: boolean;
  volume: boolean;
  volumeSlider: boolean;
  repeatType: boolean;
  trackTime: boolean;
  trackInfo: boolean;
  artwork: boolean;
  progress: ProgressUI;
  playbackRate: boolean;
};
type ProgressUI = "waveform" | "bar" | false;
type PlayListUI = "sortable" | "unSortable" | false;

CustomIcons

type CustomIcons = {
  play: ReactNode;
  pause: ReactNode;
  prev: ReactNode;
  next: ReactNode;
  repeatOne: ReactNode;
  repeatAll: ReactNode;
  repeatNone: ReactNode;
  repeatShuffle: ReactNode;
  volumeFull: ReactNode;
  volumeHalf: ReactNode;
  volumeMuted: ReactNode;
  playList: ReactNode;
};

CoverImgsCss

interface CoverImgsCss {
  artwork?: React.CSSProperties;
  listThumbnail?: React.CSSProperties;
}

Placement

type PlayerPlacement =
  | "bottom"
  | "top"
  | "bottom-left"
  | "bottom-right"
  | "top-left"
  | "top-right";

type VolumeSliderPlacement = "bottom" | "top" | "left" | "right";

type SpeedSelectorPlacement = "bottom" | "top" | "left" | "right";

type PlayListPlacement = "bottom" | "top";

type InterfacePlacement = {
  templateArea?: InterfaceGridTemplateArea;
  customComponentsArea?: InterfaceGridCustomComponentsArea<TMaxLength>;
  itemCustomArea?: InterfaceGridItemArea;
};

type InterfacePlacementKey =
  | Exclude<keyof ActiveUI, "all" | "prevNnext" | "trackTime">
  | "trackTimeCurrent"
  | "trackTimeDuration";

type InterfacePlacementValue = "row1-1" | "row1-2" | "row1-3" | "row1-4" | ... more ... | "row10-10"
/** if you apply custom components, values must be "row1-1" ~ any more */

type InterfaceGridTemplateArea = Record<InterfacePlacementKey,InterfacePlacementValue>;

type InterfaceGridCustomComponentsArea = Record<componentId,InterfacePlacementValue>;

type InterfaceGridItemArea = Partial<Record<InterfacePlacementKey, string>>;
  /** example
   * progress : 2-4
   * repeatBtn : row1-4 / 2 / row1-4 / 10
   *
   * check MDN - grid area
   * https://developer.mozilla.org/ko/docs/Web/CSS/grid-area
   */

Default interface placement

const defaultInterfacePlacement = {
  templateArea: {
    artwork: "row1-1",
    trackInfo: "row1-2",
    trackTimeCurrent: "row1-3",
    trackTimeDuration: "row1-4",
    progress: "row1-5",
    repeatType: "row1-6",
    volume: "row1-7",
    playButton: "row1-8",
    playList: "row1-9",
    playbackRate: "row1-10",
  },
};

RootContainerProps

rootContainerProps accepts any standard HTMLAttributes<HTMLDivElement> (e.g. className, style, data-*). The root container always has the class rmap-player-provider applied automatically.

⚠️ Setting the native CSS color-scheme property via rootContainerProps={{ style: { colorScheme: "dark" } }} will not toggle the player's theme. The library's theme is driven by the prefers-color-scheme media query and the [data-theme] attribute selector — use the top-level colorScheme prop instead.

Override Style

Theme mode (dark mode)

Dark mode is driven by system-theme (prefers-color-scheme: dark) by default. To force a specific theme regardless of OS preference, pass the top-level colorScheme="light" | "dark" prop on <AudioPlayer> — this applies a data-theme attribute on .rmap-player-provider which overrides the media query. You can override any color by redefining the CSS variables below on .rmap-player-provider.

@media (prefers-color-scheme: dark) {
  .rmap-player-provider {
    --rm-audio-player-interface-container: #1e1e1e;
    /* override other variables as needed */
  }
}

ID & Classnames

root ID

rm-audio-player

Multi-instance note: when multiple <AudioPlayer> instances share a page the root id is duplicated across them. Playlist and audio state are still isolated per instance (each player has its own React provider tree and its own <audio> DOM node). If you need per-instance selectors, target via the class names below rather than the id.

root ClassName

rmap-player-provider

color variables

.rmap-player-provider {
  --rm-audio-player-text-color: #2c2c2c;
  --rm-audio-player-shadow: 0 0 0;
  --rm-audio-player-interface-container: #f5f5f5;
  --rm-audio-player-volume-background: #ccc;
  --rm-audio-player-volume-panel-background: #f2f2f2;
  --rm-audio-player-volume-panel-border: #ccc;
  --rm-audio-player-volume-thumb: #5c5c5c;
  --rm-audio-player-volume-fill: rgba(0, 0, 0, 0.5);
  --rm-audio-player-volume-track: #ababab;
  --rm-audio-player-track-current-time: #0072f5;
  --rm-audio-player-track-duration: #8c8c8c;
  --rm-audio-player-progress-bar: #0072f5;
  --rm-audio-player-progress-bar-background: #393939;
  --rm-audio-player-waveform-cursor: #4b4b4b;
  --rm-audio-player-waveform-background: var(
    --rm-audio-player-progress-bar-background
  );
  --rm-audio-player-waveform-bar: var(--rm-audio-player-progress-bar);
  --rm-audio-player-sortable-list: #eaeaea;
  --rm-audio-player-sortable-list-button-active: #0072f5;
  --rm-audio-player-selected-list-item-background: #b3b3b3;
}

useAudioPlayer

Control the player externally using the useAudioPlayer hook. Must be called inside AudioPlayerStateProvider (or AudioPlayer which wraps it).

import AudioPlayer, { useAudioPlayer } from "react-modern-audio-player";

function PlayerControls() {
  const {
    isPlaying,
    currentTrack,
    currentTime,
    duration,
    togglePlay,
    next,
    prev,
    seek,
    setVolume,
    setTrack,
  } = useAudioPlayer();

  return (
    <div>
      <button onClick={togglePlay}>{isPlaying ? "Pause" : "Play"}</button>
      <button onClick={prev}>Prev</button>
      <button onClick={next}>Next</button>
      <button onClick={() => seek(30)}>+30s</button>
      <button onClick={() => setVolume(0.5)}>Volume 50%</button>
      <button onClick={() => setTrack(1)}>Track 2</button>
      <p>
        {currentTrack?.name} — {currentTime.toFixed(0)}s / {duration.toFixed(0)}s
      </p>
    </div>
  );
}

function App() {
  const playList = [{ id: 1, src: "audio.mp3", name: "Track 1" }];
  return (
    <AudioPlayer playList={playList}>
      <PlayerControls />
    </AudioPlayer>
  );
}

AudioPlayerControls

Property	Type	Description
`isPlaying`	`boolean`	Current playback state
`volume`	`number`	Current volume (0–1)
`currentTime`	`number`	Elapsed time in seconds
`duration`	`number`	Track duration in seconds
`repeatType`	`RepeatType`	Current repeat mode
`muted`	`boolean`	Whether audio is muted
`currentTrack`	`AudioData \| null`	Currently playing track
`currentIndex`	`number`	Index in playlist
`playList`	`PlayList`	Full playlist
`play()`	`() => void`	Start playback
`pause()`	`() => void`	Pause playback
`togglePlay()`	`() => void`	Toggle play/pause
`next()`	`() => void`	Skip to next track
`prev()`	`() => void`	Skip to previous track
`seek(time)`	`(time: number) => void`	Seek to time in seconds
`setVolume(vol)`	`(volume: number) => void`	Set volume (0–1, clamped)
`toggleMute()`	`() => void`	Toggle mute on/off
`setTrack(index)`	`(index: number) => void`	Jump to playlist index
`playbackRate`	`number`	Current playback rate (`1` = normal). Default `1`.
`setPlaybackRate(rate)`	`(rate: number) => void`	Set playback rate. No clamping; browser enforces HTML5 bounds.

Sub-Hooks

useAudioPlayer subscribes to all context slices. For fine-grained re-render control, use domain-specific sub-hooks:

import {
  useAudioPlayerPlayback,
  useAudioPlayerTrack,
  useAudioPlayerVolume,
  useAudioPlayerTime,
  useAudioPlayerElement,
} from "react-modern-audio-player";

// Only re-renders on play/pause and repeat type changes
function PlayButton() {
  const { isPlaying, togglePlay } = useAudioPlayerPlayback();
  return <button onClick={togglePlay}>{isPlaying ? "Pause" : "Play"}</button>;
}

// Only re-renders on time updates
function TimeDisplay() {
  const { currentTime, duration } = useAudioPlayerTime();
  return (
    <span>
      {currentTime.toFixed(0)}s / {duration.toFixed(0)}s
    </span>
  );
}

Hook	Returns
`useAudioPlayerPlayback`	`{ isPlaying, repeatType, playbackRate, play, pause, togglePlay, setPlaybackRate }`
`useAudioPlayerTrack`	`{ currentPlayId, currentIndex, playList, currentTrack, setTrack, next, prev }`
`useAudioPlayerVolume`	`{ volume, muted, setVolume, toggleMute }`
`useAudioPlayerTime`	`{ currentTime, duration, seek }`
`useAudioPlayerElement`	`{ audioEl, waveformInst }` (advanced)

Context Hooks

Components inside AudioPlayer can subscribe to only the state slice they need, avoiding unnecessary re-renders.

import {
  usePlaybackContext, // curAudioState: { isPlaying, repeatType, volume, muted, isLoadedMetaData }
  useTrackContext, // playList, curIdx, curPlayId
  useUIContext, // activeUI, interfacePlacement, playListPlacement, playerPlacement, volumeSliderPlacement
  useResourceContext, // elementRefs, customIcons, coverImgsCss
} from "react-modern-audio-player";

const MyComponent = () => {
  const { curAudioState } = usePlaybackContext();
  return <span>{curAudioState.isPlaying ? "Playing" : "Paused"}</span>;
};

Hook	Returns
`usePlaybackContext`	`{ curAudioState: AudioState }`
`useTrackContext`	`{ playList, curIdx, curPlayId }`
`useUIContext`	`{ activeUI, interfacePlacement, playListPlacement, playerPlacement, volumeSliderPlacement }`
`useResourceContext`	`{ elementRefs, customIcons, coverImgsCss }`

Custom Component

You can place a custom component anywhere in the player interface using AudioPlayer.CustomComponent. Use useAudioPlayer inside it to access player state and controls.

import AudioPlayer, {
  useAudioPlayer,
  InterfacePlacement,
  DEFAULT_INTERFACE_GRID_BOUND,
} from "react-modern-audio-player";

const activeUI: ActiveUI = {
  all: true,
};

// `as 12` pins the literal type — TS arithmetic widens
// `DEFAULT_INTERFACE_GRID_BOUND + 1` to `number`, which would erase grid-coord
const TOTAL_INTERFACE_GRID_BOUND = (DEFAULT_INTERFACE_GRID_BOUND + 1) as 12;

// `row1-${DEFAULT_INTERFACE_GRID_BOUND}` resolves to `"row1-11"` —
// the first cell beyond the default template area (which fills 1..10).
const customComponentGridArea = `row1-${DEFAULT_INTERFACE_GRID_BOUND}`;

const placement = {
  interface: {
    customComponentsArea: {
      playerCustomComponent: customComponentGridArea,
    },
  } as InterfacePlacement<typeof TOTAL_INTERFACE_GRID_BOUND>,
  /**
   * The generic on `InterfacePlacement<N>` is an exclusive upper bound on grid
   * indices — usable cells are `1..(N - 1)`. Default is
   * `DEFAULT_INTERFACE_GRID_BOUND` (= 11), giving cells `1..10` which the
   * built-in template area already occupies (e.g. `playbackRate` at `row1-10`).
   * To reserve an additional cell for the custom component, pass `<N + 1>` —
   * here `<12>` makes `row1-11` a valid coordinate.
   */
};

const CustomComponent = () => {
  const { currentTime, duration, seek, isPlaying, togglePlay } =
    useAudioPlayer();
  return (
    <>
      <button onClick={() => seek(currentTime + 30)}>+30s</button>
      <button onClick={togglePlay}>{isPlaying ? "Pause" : "Play"}</button>
      <span>
        {currentTime.toFixed(0)}s / {duration.toFixed(0)}s
      </span>
    </>
  );
};

<AudioPlayer playList={playList} placement={placement} activeUI={activeUI}>
  <AudioPlayer.CustomComponent id="playerCustomComponent">
    <CustomComponent />
  </AudioPlayer.CustomComponent>
</AudioPlayer>;

Compound Slots

AudioPlayer exposes its built-in controls as static members so you can re-place or augment individual pieces without rebuilding the whole layout.

Member	Renders
`AudioPlayer.Progress`	progress bar / waveform
`AudioPlayer.Volume`	volume trigger + slider (accepts `triggerType?: "click" \| "hover"`, `placement?: VolumeSliderPlacement`)
`AudioPlayer.PlayList`	sortable playlist drawer (accepts `initialExpanded?`)
`AudioPlayer.PlayListEmpty`	fallback rendered inside the playlist drawer when `playList` is empty
`AudioPlayer.PlayButton`	Play + Prev + Next group (Prev/Next visibility follows `activeUI.prevNnext`)
`AudioPlayer.RepeatButton`	repeat-type button
`AudioPlayer.SpeedSelector`	playback rate dropdown (accepts `options?`, `formatRate?`, `triggerType?: "click" \| "hover"`, `placement?: SpeedSelectorPlacement`)
`AudioPlayer.Artwork`	track artwork
`AudioPlayer.TrackInfo`	track title / writer
`AudioPlayer.TrackTime`	current + duration time
`AudioPlayer.CustomComponent`	user-defined slot

Each slot accepts the full GridItemLayoutProps set — gridArea?, visible?, width?, padding?, justifySelf?, UNSAFE_className? — plus its own domain props. AudioPlayer.TrackTime is the exception: it only exposes visible? because the slot maps to two grid areas internally.

Native HTML attributes (className, style, onClick, data-*, etc.) are not forwarded by compound slots. Compose the underlying primitives (PlayBtn, PrevBtn, NextBtn, etc., still exported) when full DOM control is needed; headless support with native attribute pass-through is planned for v3.

Mental model — `activeUI` vs compound children

activeUI governs the preset (default layout) — which built-in controls are shown.
Compound children are explicit placements that always render (visible defaults to true).

The two layers are orthogonal. Compound children render additively alongside the preset. To truly replace a preset control, disable it in activeUI and render the compound counterpart:

// Remove the default volume, re-place it with a custom gridArea
<AudioPlayer playList={playList} activeUI={{ all: true, volume: false }}>
  <AudioPlayer.Volume gridArea="row1-5" />
</AudioPlayer>

In development, a console.warn is emitted when a compound slot is rendered while its preset counterpart is still active, so silent duplication is easy to catch.

`AudioPlayer.PlayButton` and `activeUI.prevNnext`

AudioPlayer.PlayButton is a single slot that renders the Play + Prev + Next group as one unit. There is no separate AudioPlayer.PrevButton / AudioPlayer.NextButton compound slot — Prev / Next are part of the PlayButton compound, and there are two ways to render them.

Method 1 — `AudioPlayer.PlayButton` compound (group)

Place the whole group at a custom grid area; Prev / Next visibility inside the group follows activeUI.prevNnext (which defaults to activeUI.all):

// Re-place the full Play + Prev + Next group at a custom area
<AudioPlayer
  playList={playList}
  activeUI={{ all: true, playButton: false }} // hide the preset transport
>
  <AudioPlayer.PlayButton gridArea="row1-3" />
</AudioPlayer>

// Same compound, but render Play only — Prev / Next hidden by activeUI.prevNnext
<AudioPlayer
  playList={playList}
  activeUI={{ all: true, playButton: false, prevNnext: false }}
>
  <AudioPlayer.PlayButton gridArea="row1-3" />
</AudioPlayer>

Method 2 — primitives via `AudioPlayer.CustomComponent`

When you need finer control — placing Prev / Play / Next in different grid cells, applying custom wrappers, or attaching native HTML attributes — drop down to the PlayBtn, PrevBtn, and NextBtn primitives (still exported) and render them inside AudioPlayer.CustomComponent:

import AudioPlayer, {
  PrevBtn,
  PlayBtn,
  NextBtn,
} from "react-modern-audio-player";

<AudioPlayer
  playList={playList}
  activeUI={{ all: true, playButton: false }} // hide the preset transport
  placement={{
    interface: { customComponentsArea: { "custom-transport": "row1-3" } },
  }}
>
  <AudioPlayer.CustomComponent id="custom-transport">
    <div className="my-transport">
      <PrevBtn isVisible />
      <PlayBtn />
      <NextBtn isVisible />
    </div>
  </AudioPlayer.CustomComponent>
</AudioPlayer>;

PrevBtn / NextBtn accept an isVisible boolean for symmetry with the compound group's visibility logic; pass false to omit them. Use Method 2 when Method 1's group placement and activeUI.prevNnext toggle aren't enough.

Custom empty-playlist UI

Pass children to AudioPlayer.PlayListEmpty to render a custom node inside the playlist drawer when playList is empty. Omit the slot to keep the default (drawer content renders nothing).

<AudioPlayer playList={[]}>
  <AudioPlayer.PlayListEmpty>
    <div className="my-empty">Playlist is empty</div>
  </AudioPlayer.PlayListEmpty>
</AudioPlayer>

PlayListEmpty is a marker slot; its children are consumed by the drawer via context and the component itself does not render in-place.

Accessibility

The player follows WAI-ARIA patterns and is fully navigable by keyboard and screen readers.

Keyboard support

All controls are reachable via Tab and respond to standard keyboard activation. The playlist uses the WAI-ARIA "Listbox with Rearrangeable Options" pattern:

Key	Action
`Tab` / `Shift+Tab`	Move focus between player controls
`Space` / `Enter`	Activate the focused button (play/pause, prev/next, repeat, mute, playlist)
`ArrowUp` / `ArrowDown`	Move focus between playlist items
`Alt+ArrowUp` / `Alt+ArrowDown`	Reorder the focused playlist item
`Enter` / `Space` on a playlist item	Select and play that track

Drag-and-drop reordering is preserved as an alternative — keyboard and mouse both call the same onReorder handler.

Gotchas

Common integration mistakes to avoid:

Don't toggle the theme via rootContainerProps.style.colorScheme. The native CSS color-scheme property does not switch the player's theme. Use the top-level colorScheme prop, which drives the [data-theme] attribute and re-initializes the waveform colors.
Set the InterfacePlacement generic when placing customComponentsArea beyond row 9. TypeScript rejects values past the default range, so use InterfacePlacement<N> where N is (max row length + 1) — e.g. InterfacePlacement<11> for "row1-10" (see Custom Component).
AudioPlayer.CustomComponent accepts a single React element child. It uses React.cloneElement internally, so passing multiple children or a primitive (string, number) will throw.
Volume is 0..1, not 0..100. setVolume clamps out-of-range values, so setVolume(50) silently becomes setVolume(1).
Compound slots don't forward native HTML attributes. <AudioPlayer.Volume className="..."> is rejected by TypeScript — only GridItemLayoutProps (layout) pass through. Compose the underlying primitives (PlayBtn, PrevBtn, NextBtn, etc., still exported) when you need className, style, onClick, or data-*. Full headless support is planned for v3.
id: 0 is a valid track id. The reducer uses nullish checks, so tracks with id: 0 are handled correctly — don't filter them out of playList on the assumption that zero is falsy.
Don't import the CSS manually. Styles are auto-injected via sideEffects: ["*.css"]; import "react-modern-audio-player/dist/index.css" will 404 or double-load.
Multiple mounted <AudioPlayer> instances don't share React state, but they do share the user's speakers. Each instance has its own provider and its own <audio> element, so the state is isolated — but if two instances both play, the user hears both tracks simultaneously. Coordinate playback yourself (e.g. pause the others when one play() fires).

Example

function App() {
  return (
    <div>
      <AudioPlayer
        playList={playList}
        audioInitialState={{
          muted: true,
          volume: 0.2,
          curPlayId: 1,
        }}
        placement={{
          interface: {
            templateArea: {
              trackTimeDuration: "row1-5",
              progress: "row1-4",
              playButton: "row1-6",
              repeatType: "row1-7",
              volume: "row1-8",
            },
          },
          player: "bottom-left",
        }}
        activeUI={{
          all: true,
          progress: "waveform",
        }}
      />
    </div>
  );
}

Name		Name	Last commit message	Last commit date
Latest commit History 290 Commits
.changeset		.changeset
.github		.github
.husky		.husky
agents		agents
conventions		conventions
package		package
storybook		storybook
test		test
.coderabbit.yaml		.coderabbit.yaml
.eslintignore		.eslintignore
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
.yarnrc.yml		.yarnrc.yml
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
package.json		package.json
playwright.config.ts		playwright.config.ts
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

React Modern Audio Player

Highlights

DEMO

Flexible and Customizable UI

Waveform progress with wavesurfer.js

Customizable layout and placement — with light & dark themes

Full View

Position Change

Particular View

Installation

Requirements

Quick Start

Next.js / Server Components

Table of Contents

Props

PlayList

Empty playlist handling

InitialStates

ActiveUI

CustomIcons

CoverImgsCss

Placement

Default interface placement

RootContainerProps

Override Style

Theme mode (dark mode)

ID & Classnames

root ID

root ClassName

color variables

useAudioPlayer

AudioPlayerControls

Sub-Hooks

Context Hooks

Custom Component

Compound Slots

Mental model — activeUI vs compound children

AudioPlayer.PlayButton and activeUI.prevNnext

Method 1 — AudioPlayer.PlayButton compound (group)

Method 2 — primitives via AudioPlayer.CustomComponent

Custom empty-playlist UI

Accessibility

Keyboard support

Gotchas

Example

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 15

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Waveform progress with `wavesurfer.js`

Mental model — `activeUI` vs compound children

`AudioPlayer.PlayButton` and `activeUI.prevNnext`

Method 1 — `AudioPlayer.PlayButton` compound (group)

Method 2 — primitives via `AudioPlayer.CustomComponent`

Packages