## 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
# **Flexible and Customizable UI**
## Waveform progress with `wavesurfer.js`
## Customizable layout and placement — with light & dark themes
### Full View
### Position Change
### Particular View
# **Installation**
```tsx
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**
```tsx
import AudioPlayer from "react-modern-audio-player";
const playList = [
{
name: "name",
writer: "writer",
img: "image.jpg",
src: "audio.mp3",
id: 1,
},
];
function Player() {
return ;
}
```
# **Next.js / Server Components**
This library includes the `'use client'` directive and can be imported directly in Next.js App Router.
**Server Component** — render `` with static props (no hooks, no compound components):
```tsx
// 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 ;
}
```
**Client Component** — use `useAudioPlayer` hooks or `AudioPlayer.CustomComponent`:
```tsx
"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 ;
}
export default function PlayerPage() {
return (
);
}
```
> **Why `'use client'`?** The library's `'use client'` directive marks the **client boundary** — it allows Server Components to import and render ``. 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](#playlist) · [InitialStates](#initialstates) · [ActiveUI](#activeui) · [Placement](#placement) · [RootContainerProps](#rootcontainerprops) |
| **Override & Style** | [CustomIcons](#customicons) · [CoverImgsCss](#coverimgscss) · [Theme mode](#theme-mode-dark-mode) · [ID & Classnames](#id--classnames) |
| **Player Hook API** | [useAudioPlayer](#useaudioplayer) · [AudioPlayerControls](#audioplayercontrols) · [Sub-Hooks](#sub-hooks) |
| **Custom Component** | [Custom Component](#custom-component) · [Compound Slots](#compound-slots) |
| **Accessibility** | [Keyboard support](#keyboard-support) |
| **Gotchas** | [Gotchas](#gotchas) |
| **Example** | [Example](#example) |
# Props
```tsx
interface AudioPlayerProps {
playList: PlayList;
audioInitialState?: InitialStates;
audioRef?: React.MutableRefObject;
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](#playlist) | [ ] |
| `audioInitialState` | [InitialStates](#initialstates) | isPlaying: false repeatType: "ALL" volume: 1 |
| `activeUI` | [ActiveUI](#activeui) | playButton : true |
| `customIcons` | [CustomIcons](#customicons) | undefined |
| `coverImgsCss` | [CoverImgsCss](#coverimgscss) | undefined |
| `placement` | [Placement](#placement) | playListPlacement : "bottom" interfacePlacement :[DefaultInterfacePlacement](#default-interface-placement) |
| `rootContainerProps` | [RootContainerProps](#rootcontainerprops) | width: 100% position: 'static' className: rmap-player-provider |
| `colorScheme` | `"light" \| "dark"` | undefined (follows OS `prefers-color-scheme`) |
## PlayList
```tsx
type PlayList = Array;
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:
```tsx
function App() {
const [tracks, setTracks] = useState([]);
useEffect(() => {
fetchTracks().then(setTracks);
}, []);
// Safe — the player mounts with no audio source and activates once tracks arrive.
return ;
}
```
- 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
```tsx
type InitialStates = Omit<
React.AudioHTMLAttributes,
"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
```tsx
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
```tsx
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
```tsx
interface CoverImgsCss {
artwork?: React.CSSProperties;
listThumbnail?: React.CSSProperties;
}
```
## Placement
```tsx
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;
itemCustomArea?: InterfaceGridItemArea;
};
type InterfacePlacementKey =
| Exclude
| "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;
type InterfaceGridCustomComponentsArea = Record;
type InterfaceGridItemArea = Partial>;
/** 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
```tsx
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` (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`](#theme-mode-dark-mode) 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 `` — 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`.
```css
@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 `` 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 `
## Customizable layout and placement — with light & dark themes
### Full View
