https://github.com/gfazioli/mantine-audio
A Mantine-native audio player for React with waveform visualization and live spectrum analyzer, built on Web Audio API. Compound component API + headless useAudio hook.
https://github.com/gfazioli/mantine-audio
audio audio-player component compound-component headless mantine mantine-extension mantine-ui mantine-v9 podcast react react-audio react-component spectrum-analyzer typescript waveform web-audio-api
Last synced: 4 days ago
JSON representation
A Mantine-native audio player for React with waveform visualization and live spectrum analyzer, built on Web Audio API. Compound component API + headless useAudio hook.
- Host: GitHub
- URL: https://github.com/gfazioli/mantine-audio
- Owner: gfazioli
- License: mit
- Created: 2026-05-19T16:25:18.000Z (11 days ago)
- Default Branch: master
- Last Pushed: 2026-05-20T09:11:23.000Z (10 days ago)
- Last Synced: 2026-05-20T11:55:57.550Z (10 days ago)
- Topics: audio, audio-player, component, compound-component, headless, mantine, mantine-extension, mantine-ui, mantine-v9, podcast, react, react-audio, react-component, spectrum-analyzer, typescript, waveform, web-audio-api
- Language: TypeScript
- Homepage: https://gfazioli.github.io/mantine-audio/
- Size: 12.2 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Mantine Audio Component
[](https://www.npmjs.com/package/@gfazioli/mantine-audio)
[](https://www.npmjs.com/package/@gfazioli/mantine-audio)
[](https://www.npmjs.com/package/@gfazioli/mantine-audio)
---
[
❤️ If this component has been useful to you or your team, please consider becoming a sponsor
](https://github.com/sponsors/gfazioli?o=esc)
## Overview
This component is built on top of the [Mantine](https://mantine.dev/) library.
The [Mantine Audio](https://gfazioli.github.io/mantine-audio/) component is a Mantine-native audio player for React with **waveform visualisation** and a **live spectrum analyser**, built on the Web Audio API. It ships as three layers in a single package: a polished default `` with four variants, a fully composable compound API (ten sub-components you can reorder and restyle), and a fully headless `useAudio` hook to build 100% custom UIs.
## Features
- 🎧 **Drop-in player** — `` and you have a styled, accessible audio player
- 🧩 **Compound API** — 10 sub-components (`Audio.PlayButton`, `Audio.Timeline`, `Audio.Waveform`, `Audio.Spectrum`, `Audio.VolumeSlider`, `Audio.SpeedControl`, …) reorderable and re-styleable
- 🪝 **Headless `useAudio` hook** — 16 state values + 12 actions for fully custom UIs
- 🌊 **Waveform visualisation** — peaks decoded via Web Audio + click/drag to seek, 60fps playhead tracking via RAF
- 🎚️ **Live spectrum analyser** — `AnalyserNode` driven, solid or gradient bars, optional mirror
- 🔀 **Multiple `` support** — `sources={[…]}` for codec / format / media-query fallbacks + `fallbackSrc` for runtime errors
- 🎛️ **5 sizes × 4 variants** — `xs/sm/md/lg/xl` × `overlay/minimal/floating/bordered` (all CSS-driven via data attributes)
- 🌅 **`asBackground` preset** — turn the same player into a hero / section ambient track in one line
- 🎚️ **Scrub-with-sound** — optional `scrubSound` lets the user hear snippets while dragging (Audacity / iTunes style)
- ⌨️ **Keyboard shortcuts** — Space, J/K/L, ←/→, ↑/↓, M, > / <
- 🎨 **Full Styles API** — `classNames`, `styles`, `vars`, `unstyled`, theme-aware out of the box
- 📦 **TypeScript** — strict types, every prop documented
> [!note]
>
> → [Demo and Documentation](https://gfazioli.github.io/mantine-audio/) → [More Mantine Components](https://mantine-extensions.vercel.app/)
## Installation
```sh
npm install @gfazioli/mantine-audio
```
or
```sh
yarn add @gfazioli/mantine-audio
```
After installation import package styles at the root of your application:
```tsx
import '@gfazioli/mantine-audio/styles.css';
```
## Usage
```tsx
import { Audio } from '@gfazioli/mantine-audio';
function Demo() {
return ;
}
```
Compound layout with waveform on top and a custom skip button:
```tsx
```
Headless usage with the `useAudio` hook:
```tsx
import { useAudio } from '@gfazioli/mantine-audio';
function MyPlayer() {
const { playing, currentTime, duration, peaks, analyser, toggle, audioRef } = useAudio({
src: '/track.mp3',
});
return (
{playing ? 'Pause' : 'Play'}
{currentTime.toFixed(1)} / {duration.toFixed(1)}
);
}
```
## Sponsor
[
❤️ If this component has been useful to you or your team, please consider becoming a sponsor
](https://github.com/sponsors/gfazioli?o=esc)
Your support helps me:
- Keep the project actively maintained with timely bug fixes and security updates
- Add new features, improve performance, and refine the developer experience
- Expand test coverage and documentation for smoother adoption
- Ensure long‑term sustainability without relying on ad hoc free time
- Prioritize community requests and roadmap items that matter most
Open source thrives when those who benefit can give back—even a small monthly contribution makes a real difference. Sponsorships help cover maintenance time, infrastructure, and the countless invisible tasks that keep a project healthy.
Your help truly matters.
💚 [Become a sponsor](https://github.com/sponsors/gfazioli?o=esc) today and help me keep this project reliable, up‑to‑date, and growing for everyone.
---
[](https://www.star-history.com/#gfazioli/mantine-audio&Timeline)