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
• 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

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.

Table of Contents

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
Accessibility	Keyboard support
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;
  };
  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;
};

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;
};
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 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 ... | "row9-9"
/** 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",
  },
};

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

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

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, play, pause, togglePlay }
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,
} from "react-modern-audio-player";

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

const placement = {
  interface: {
    customComponentsArea: {
      playerCustomComponent: "row1-10",
    },
  } as InterfacePlacement<11>,
  /**
   * set the generic value of InterfacePlacement to the max interface length + 1
   * for correct "row1-10" autocompletion
   */
};

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>;

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.

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>
  );
}