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