tailwind-react-music-player

An accessible, themeable HTML5 music player component for React, styled with Tailwind CSS — with a headless useMusicPlayer hook if you want to bring your own UI.

Live demo — try the player in your browser before installing.

Features

• Full player UI: mini controller, fixed bottom panel, mobile layout, playlist drawer, floating lyric overlay
• Headless useMusicPlayer hook — same engine, your own markup
• Accessible: labelled controls, keyboard shortcuts, focus management, reduced-motion support
• Themeable: dark / light / auto themes, runtime --trmp-* CSS custom properties, per-slot icon overrides
• Playlist management: drag-to-sort (SortableJS), remove, reorder, list updates that preserve the current track
• Lyrics: LRC parsing and sync (parseLrc is exported if you roll your own)
• Volume fade in/out, perceptual volume mapping, persistence to localStorage
• Media Session API integration (lock-screen / hardware-key controls)
• Typed end-to-end; the public API surface is src/types.ts

Requirements

• React >= 19 (MusicPlayer takes ref as a plain prop — a React 19 feature)
• ESM-only — no CJS or UMD build; CJS consumers must import() or go through a bundler
• Node >= 22.19 for the build tooling (the published bundle has no runtime Node dependency)

Install

yarn add tailwind-react-music-player
# or
npm install tailwind-react-music-player

import MusicPlayer from 'tailwind-react-music-player'
import 'tailwind-react-music-player/styles.css' // required — styles are a separate entry point

Quick start

import MusicPlayer from 'tailwind-react-music-player'
import 'tailwind-react-music-player/styles.css'

const audioLists = [
  {
    name: 'Despacito',
    singer: 'Luis Fonsi',
    cover: 'https://example.com/cover.jpg',
    musicSrc: 'https://example.com/despacito.mp3',
    // musicSrc can also resolve lazily:
    // musicSrc: () => fetch('/api/sign').then((r) => r.text()),
    lyric: '[00:00.00]Line one of the lyric',
  },
]

export default function App() {
  return <MusicPlayer audioLists={audioLists} />
}

Props

MusicPlayerProps = UseMusicPlayerOptions & MusicPlayerUIProps — the options below are also accepted directly by useMusicPlayer. src/types.ts is the source of truth.

Playlist, playback and state

Most state can be controlled (value + onChange) or uncontrolled (default*).

¹ <MusicPlayer> defaults defaultMode to 'mini'; bare useMusicPlayer defaults to 'full'.

AudioTrack:

interface AudioTrack {
  name?: React.ReactNode
  singer?: React.ReactNode
  cover?: string
  musicSrc: string | (() => Promise<string>)
  lyric?: string
  duration?: number
}

Callbacks

Every callback receives a unified AudioInfo payload (track, index, tracks, currentTime, duration, volume, muted, paused, ended, readyState, networkState, playMode, currentLyric).

UI props

Ref handle

MusicPlayer takes a React 19 ref prop exposing MusicPlayerHandle: every MusicPlayerActions method, the live audio element, and destroy().

import { useRef } from 'react'
import MusicPlayer, {
  type MusicPlayerHandle,
} from 'tailwind-react-music-player'

function App() {
  const playerRef = useRef<MusicPlayerHandle>(null)

  return (
    <>
      <MusicPlayer ref={playerRef} audioLists={audioLists} />
      <button onClick={() => playerRef.current?.togglePlay()}>toggle</button>
      <button onClick={() => playerRef.current?.seekBy(10)}>+10s</button>
    </>
  )
}

MusicPlayerActions: play, pause, togglePlay, playIndex, playId, next, prev, reload, seek, seekBy, setVolume, volumeBy, toggleMute, setPlayMode, cyclePlayMode, setTheme, toggleTheme, setMode, toggleMode, removeTrack, clearTracks, reorderTracks, download, getAudioInfo.

Headless: useMusicPlayer

Build your own UI on the same engine. Render an <audio> element with player.audioProps and wire player.state/player.actions to your controls.

import { useMusicPlayer } from 'tailwind-react-music-player'

function MyPlayer() {
  const { state, actions, audioProps } = useMusicPlayer({
    audioLists,
    onTrackChange: (info) => console.log('now playing', info.track?.name),
  })

  return (
    <div>
      <audio {...audioProps} />
      <p>
        {state.track?.name} — {state.status}
      </p>
      <button onClick={actions.prev}>prev</button>
      <button onClick={actions.togglePlay}>
        {state.status === 'playing' ? 'pause' : 'play'}
      </button>
      <button onClick={actions.next}>next</button>
      <input
        type="range"
        min={0}
        max={state.duration || 0}
        value={state.currentTime}
        onChange={(e) => actions.seek(e.target.valueAsNumber)}
      />
    </div>
  )
}

useMusicPlayer(options) returns { state, actions, audioRef, audioProps } — see MusicPlayerState, MusicPlayerActions and MusicPlayerAudioProps in src/types.ts.

Theming

The player renders under a .trmp-root element carrying data-theme (dark | light), data-mode, data-layout (desktop | mobile) and data-status attributes.

<MusicPlayer theme="auto" /> // follows prefers-color-scheme

CSS custom properties

Every design token is a --trmp-* variable you can override at runtime — globally, or scoped to a subtree:

:root {
  --trmp-color-primary: #ff5500;
}
.my-player-scope {
  --trmp-color-panel: #1e1e2e;
}

The light theme is a token remap on .trmp-root[data-theme='light']; the mobile layout remaps on .trmp-root[data-layout='mobile']. To customise a single theme, override tokens inside the corresponding selector:

.trmp-root[data-theme='light'] {
  --trmp-color-primary: #7c3aed;
}

Semantic class hooks

Stable trmp-* classes are part of the public styling API and always present alongside utility classes: .trmp-root, .trmp-panel, .trmp-mobile, .trmp-mini, .trmp-playlist, .trmp-lyric, .trmp-toast, .trmp-cover, .trmp-icon-button, .trmp-theme-switch, .trmp-time, .trmp-track-title, .trmp-range-wrap, .trmp-range, .trmp-sortable-highlight.

Icons

icons accepts per-slot ReactNode overrides. Slots: play, pause, prev, next, loading, volume, mute, download, reload, lyric, playlist, close, delete, minimize, destroy, order, orderLoop, singleLoop, shuffle, collapse, empty, controller.

<MusicPlayer icons={{ play: <MyPlayIcon />, playlist: <MyListIcon /> }} />

defaultIcons is exported if you want to wrap or inspect the defaults.

Locales

Built-in locales: en_US, en_GB, zh_CN (all exported via locales). locale accepts an id or a partial override merged over en_US:

<MusicPlayer locale="zh_CN" />
<MusicPlayer locale={{ play: 'Play now', emptyPlaylist: 'Nothing here yet' }} />

createLocale(partial, base?) and resolveLocale(input) are exported for reuse; the full string list is the Locale type in src/i18n/types.ts.

Accessibility

• All controls are labelled (aria-label/title) and keyboard-reachable
• The theme switch is role="switch"; the playlist is a dialog with focus management; lyrics announce via an aria-live overlay
• prefers-reduced-motion collapses decorative animation

Enable keyboard shortcuts with keyboardShortcuts. They fire on keydown within the player (ignored from text fields and handled events):

Playlist rows additionally support Alt+arrow keyboard reordering. useKeyboardShortcuts is exported if you want the same bindings in a headless UI.

SSR

The module is SSR-importable — it ships a "use client" banner and touches document only inside effects. By default the component renders nothing until the portal target resolves after mount; pass container={null} to render inline without a portal.

Migrating from v4

v5 is a full rewrite — React 19, hooks, ESM-only, new prop names and a new token system. See MIGRATION.md.

Development

See CONTRIBUTING.md.

License

MIT