Wave Minimap

A shadcn-styled waveform player with a minimap overview built on wavesurfer.js MinimapPlugin.

Loading...
import WaveMinimap from "@/components/waves-cn/wave-minimap";export default function WaveMinimapDemo() {  return (    <div className="w-full mx-auto p-6">      <WaveMinimap        src="/coastline.mp3"        title="Minimap Navigation"      />    </div>  );}

Installation

pnpm dlx shadcn@latest add @waves-cn/wave-minimap
npx shadcn@latest add @waves-cn/wave-minimap
yarn dlx shadcn@latest add @waves-cn/wave-minimap
bunx --bun shadcn@latest add @waves-cn/wave-minimap

Install the peer dependency.

npm install wavesurfer.js

Install the required shadcn primitives.

npx shadcn@latest add card button slider skeleton

Copy wave-cn.tsx into your project.

import {  useCallback,  useEffect,  useMemo,  useRef,  useState,  memo,  type ReactElement,  type RefObject,} from "react";import WaveSurfer, {  type WaveSurferEvents,  type WaveSurferOptions,} from "wavesurfer.js";// ─── Types ───────────────────────────────────────────────────────────────────type WavesurferEventHandler<T extends unknown[]> = (  wavesurfer: WaveSurfer,  ...args: T) => void;/** `onReady`, `onPlay`, `onTimeupdate`, … — one prop per wavesurfer.js event. */export type OnWavesurferEvents = {  [K in keyof WaveSurferEvents as `on${Capitalize<K>}`]?: WavesurferEventHandler<    WaveSurferEvents[K]  >;};export type PartialWavesurferOptions = Omit<WaveSurferOptions, "container">;type WavesurferPlugin = NonNullable<WaveSurferOptions["plugins"]>[number];export type WavesurferProps = PartialWavesurferOptions &  OnWavesurferEvents & {    className?: string;  };// ─── Defaults ────────────────────────────────────────────────────────────────export const WAVESURFER_DEFAULTS = {  waveColor: "var(--muted-foreground)",  progressColor: "var(--primary)",  height: 64,  barWidth: 3,  barGap: 2,  barRadius: 2,  minPxPerSec: 1,  cursorWidth: 0,} as const satisfies Partial<WaveSurferOptions>;// ─── Helpers ─────────────────────────────────────────────────────────────────/** Formats seconds as `m:ss`. Negative or non-finite input renders as `0:00`. */export function formatTime(seconds: number): string {  if (!Number.isFinite(seconds) || seconds < 0) return "0:00";  const m = Math.floor(seconds / 60);  const s = Math.floor(seconds % 60);  return `${m}:${s.toString().padStart(2, "0")}`;}const EVENT_PROP_RE = /^on([A-Z])/;const isEventProp = (key: string) => EVENT_PROP_RE.test(key);const getEventName = (key: string) =>  key.replace(EVENT_PROP_RE, (_, $1) =>    $1.toLowerCase(),  ) as keyof WaveSurferEvents;/** * Options that require a brand-new WaveSurfer instance when they change. * Every other option is applied in place through `wavesurfer.setOptions()`, * so cosmetic changes (bar width, height, colors…) never re-fetch the audio. * * `plugins` and `peaks` are compared by reference: memoize them in the caller * (`useMemo`) or the player will be recreated on every render. */const STRUCTURAL_KEYS = [  "url",  "media",  "plugins",  "peaks",  "duration",  "sampleRate",  "backend",  "mediaControls",] as const satisfies readonly (keyof WaveSurferOptions)[];type StructuralKey = (typeof STRUCTURAL_KEYS)[number];function isStructuralKey(key: string): key is StructuralKey {  return (STRUCTURAL_KEYS as readonly string[]).includes(key);}function splitProps(props: WavesurferProps) {  const { className, ...rest } = props;  const options: Partial<WaveSurferOptions> = {};  const events: OnWavesurferEvents = {};  for (const key in rest) {    const value = rest[key as keyof typeof rest];    if (isEventProp(key)) {      events[key as keyof OnWavesurferEvents] = value as never;    } else {      options[key as keyof PartialWavesurferOptions] = value as never;    }  }  return { className, options, events };}function pickUpdatableOptions(  options: Partial<WaveSurferOptions>,): Partial<WaveSurferOptions> {  const out: Partial<WaveSurferOptions> = {};  for (const key in options) {    if (isStructuralKey(key)) continue;    const value = options[key as keyof WaveSurferOptions];    if (value === undefined) continue; // keep WAVESURFER_DEFAULTS in place    out[key as keyof WaveSurferOptions] = value as never;  }  return out;}/** * Keys whose value changed between two option objects. Only those are sent to * `setOptions()`, so re-rendering with the same props never resets state that * the user changed through the instance (zoom level, playback rate…). */function diffOptions(  prev: Partial<WaveSurferOptions>,  next: Partial<WaveSurferOptions>,): Partial<WaveSurferOptions> {  const patch: Partial<WaveSurferOptions> = {};  const keys = new Set([...Object.keys(prev), ...Object.keys(next)]);  for (const key of keys) {    const k = key as keyof WaveSurferOptions;    if (prev[k] !== next[k]) patch[k] = next[k] as never;  }  return patch;}/** Stable string for the updatable, serialisable part of the options. */function updatableOptionsKey(options: Partial<WaveSurferOptions>): string {  const out: Record<string, unknown> = {};  for (const key in options) {    if (isStructuralKey(key)) continue;    const value = options[key as keyof WaveSurferOptions];    if (typeof value === "function") continue;    if (typeof HTMLElement !== "undefined" && value instanceof HTMLElement)      continue;    out[key] = value;  }  return JSON.stringify(out);}/** * Plugins passed to `<WavesurferPlayer>` act as templates. wavesurfer.js destroys * plugins together with the instance, so a fresh copy is created from each * template every time the instance is (re)created. */function instantiatePlugins(  plugins: WaveSurferOptions["plugins"],): WaveSurferOptions["plugins"] {  return plugins?.map((plugin) => {    const Plugin = plugin.constructor as new (      options: unknown,    ) => WavesurferPlugin;    const options = (plugin as unknown as { options?: unknown }).options;    return new Plugin(options);  });}// ─── CSS var resolver ────────────────────────────────────────────────────────const CSS_VAR_RE = /^var\((--[^,)]+)(?:\s*,\s*([^)]+))?\)$/;function resolveCssVar(value: string): string {  if (typeof window === "undefined") return value;  const match = CSS_VAR_RE.exec(value.trim());  if (!match) return value;  const [, name, fallback] = match;  const root = getComputedStyle(document.documentElement)    .getPropertyValue(name)    .trim();  const body = root    ? ""    : getComputedStyle(document.body).getPropertyValue(name).trim();  const raw = root || body || fallback?.trim() || "";  if (!raw) return value;  // shadcn v3 stored bare HSL channels ("222.2 47.4% 11.2%"); canvas needs a full color.  const isHslChannels = /^[\d.]+\s+[\d.]+%\s+[\d.]+%$/.test(raw);  return isHslChannels ? `hsl(${raw})` : raw;}/** * Resolves a `var(--token)` string to its computed value so it can be handed to * a `<canvas>` (wavesurfer, minimap, spectrogram…). Re-resolves when the theme * class / `data-theme` attribute changes on `<html>` or `<body>`. * * Non-`var()` values pass straight through. */export function useCssVar(value: string): string {  const [resolved, setResolved] = useState(() => resolveCssVar(value));  const [prevValue, setPrevValue] = useState(value);  // Re-resolve synchronously when the input changes (derived state pattern).  if (prevValue !== value) {    setPrevValue(value);    setResolved(resolveCssVar(value));  }  useEffect(() => {    if (!CSS_VAR_RE.test(value.trim())) return;    const update = () => setResolved(resolveCssVar(value));    const observer = new MutationObserver(update);    const config = {      attributes: true,      attributeFilter: ["class", "style", "data-theme"],    };    observer.observe(document.documentElement, config);    observer.observe(document.body, config);    return () => observer.disconnect();  }, [value]);  return resolved;}// ─── <WavesurferPlayer> ──────────────────────────────────────────────────────function WavesurferPlayerBase(props: WavesurferProps): ReactElement {  const containerRef = useRef<HTMLDivElement | null>(null);  const wsRef = useRef<WaveSurfer | null>(null);  const { className, options, events } = splitProps(props);  // Colors: resolve CSS vars for the canvas, re-resolve on theme change.  const waveColor =    (options.waveColor as string | undefined) ?? WAVESURFER_DEFAULTS.waveColor;  const progressColor =    (options.progressColor as string | undefined) ??    WAVESURFER_DEFAULTS.progressColor;  const resolvedWaveColor = useCssVar(waveColor);  const resolvedProgressColor = useCssVar(progressColor);  // Latest props in refs so the creation effect never needs them as deps.  const latest = useRef({ options, events, resolvedWaveColor, resolvedProgressColor });  useEffect(() => {    latest.current = { options, events, resolvedWaveColor, resolvedProgressColor };  });  const [isReady, setIsReady] = useState(false);  /** Options last applied to the current instance (creation or setOptions). */  const applied = useRef<Partial<WaveSurferOptions> | null>(null);  const { url, media, plugins, peaks, duration, sampleRate, backend, mediaControls } =    options;  const height = options.height ?? WAVESURFER_DEFAULTS.height;  // ── Create / destroy the instance  useEffect(() => {    const container = containerRef.current;    if (!container) return;    const current = latest.current;    const initial = {      ...pickUpdatableOptions(current.options),      waveColor: current.resolvedWaveColor,      progressColor: current.resolvedProgressColor,    };    const ws = WaveSurfer.create({      ...WAVESURFER_DEFAULTS,      ...initial,      url,      media,      peaks,      duration,      sampleRate,      backend,      mediaControls,      plugins: instantiatePlugins(plugins),      container,    });    wsRef.current = ws;    applied.current = initial;    const unsubs: Array<() => void> = [      ws.on("load", () => setIsReady(false)),      ws.on("ready", () => setIsReady(true)),      ws.on("destroy", () => setIsReady(false)),    ];    // Forward every `onX` prop present at mount to the matching wavesurfer event.    // Handlers are read through the ref at call time, so parents can pass inline    // functions without causing re-subscription.    for (const name of Object.keys(current.events)) {      const event = getEventName(name);      unsubs.push(        ws.on(event, (...args) => {          const handler = latest.current.events[            name as keyof OnWavesurferEvents          ] as WavesurferEventHandler<WaveSurferEvents[typeof event]> | undefined;          handler?.(ws, ...args);        }),      );    }    return () => {      unsubs.forEach((fn) => fn());      ws.destroy();      wsRef.current = null;      applied.current = null;    };  }, [url, media, plugins, peaks, duration, sampleRate, backend, mediaControls]);  // ── Apply changed options in place (never the full set: see diffOptions)  const optionsKey = updatableOptionsKey(options);  useEffect(() => {    const ws = wsRef.current;    if (!ws || !applied.current) return;    const next = {      ...pickUpdatableOptions(latest.current.options),      waveColor: resolvedWaveColor,      progressColor: resolvedProgressColor,    };    const patch = diffOptions(applied.current, next);    applied.current = next;    if (Object.keys(patch).length > 0) ws.setOptions(patch);  }, [optionsKey, resolvedWaveColor, resolvedProgressColor]);  return (    <div className={className} style={{ position: "relative" }}>      {!isReady && (        <div          aria-hidden          className="absolute inset-0 animate-pulse rounded bg-muted"          style={{ height }}        />      )}      <div ref={containerRef} style={isReady ? undefined : { opacity: 0 }} />    </div>  );}/** * Declarative wrapper around `WaveSurfer.create()`. * * - Every `WaveSurferOptions` key is accepted as a prop. * - Every wavesurfer event is available as `on<Event>` (`onReady`, `onTimeupdate`…). * - Changing `url`, `media`, `plugins`, `peaks`, `duration`, `sampleRate`, *   `backend` or `mediaControls` recreates the instance; anything else is applied *   through `setOptions()` without re-decoding. * - Memoize `plugins` and `peaks` (they are compared by reference). */const WavesurferPlayer = memo(WavesurferPlayerBase, (prev, next) => {  // Event handler identity never matters (read through a ref); everything else does.  const keys = new Set([...Object.keys(prev), ...Object.keys(next)]);  for (const key of keys) {    if (isEventProp(key)) continue;    if (prev[key as keyof WavesurferProps] !== next[key as keyof WavesurferProps])      return false;  }  return true;});WavesurferPlayer.displayName = "WavesurferPlayer";export default WavesurferPlayer;// ─── useWavesurfer ───────────────────────────────────────────────────────────/** * Imperative counterpart of `<WavesurferPlayer>`: you own the container element, * the hook owns the instance. Same recreate / setOptions rules apply. */export function useWavesurfer({  container,  waveColor = WAVESURFER_DEFAULTS.waveColor,  progressColor = WAVESURFER_DEFAULTS.progressColor,  ...options}: PartialWavesurferOptions & {  container: RefObject<HTMLDivElement | null>;}) {  const resolvedWaveColor = useCssVar(waveColor as string);  const resolvedProgressColor = useCssVar(progressColor as string);  const [wavesurfer, setWavesurfer] = useState<WaveSurfer | null>(null);  const [isReady, setIsReady] = useState(false);  const [isPlaying, setIsPlaying] = useState(false);  const [currentTime, setCurrentTime] = useState(0);  const latest = useRef({ options, resolvedWaveColor, resolvedProgressColor });  useEffect(() => {    latest.current = { options, resolvedWaveColor, resolvedProgressColor };  });  const applied = useRef<Partial<WaveSurferOptions> | null>(null);  const { url, media, plugins, peaks, duration, sampleRate, backend, mediaControls } =    options;  useEffect(() => {    if (!container.current) return;    const current = latest.current;    const initial = {      ...pickUpdatableOptions(current.options),      waveColor: current.resolvedWaveColor,      progressColor: current.resolvedProgressColor,    };    const ws = WaveSurfer.create({      ...WAVESURFER_DEFAULTS,      ...initial,      url,      media,      peaks,      duration,      sampleRate,      backend,      mediaControls,      plugins: instantiatePlugins(plugins),      container: container.current,    });    applied.current = initial;    const unsubs = [      ws.on("load", () => {        setIsReady(false);        setIsPlaying(false);        setCurrentTime(0);      }),      ws.on("ready", () => setIsReady(true)),      ws.on("play", () => setIsPlaying(true)),      ws.on("pause", () => setIsPlaying(false)),      ws.on("finish", () => setIsPlaying(false)),      ws.on("timeupdate", (t) => setCurrentTime(t)),      ws.on("destroy", () => {        setIsReady(false);        setIsPlaying(false);      }),    ];    setWavesurfer(ws);    return () => {      unsubs.forEach((fn) => fn());      ws.destroy();      applied.current = null;      setWavesurfer(null);    };  }, [    container,    url,    media,    plugins,    peaks,    duration,    sampleRate,    backend,    mediaControls,  ]);  const optionsKey = updatableOptionsKey(options);  useEffect(() => {    if (!wavesurfer || !applied.current) return;    const next = {      ...pickUpdatableOptions(latest.current.options),      waveColor: resolvedWaveColor,      progressColor: resolvedProgressColor,    };    const patch = diffOptions(applied.current, next);    applied.current = next;    if (Object.keys(patch).length > 0) wavesurfer.setOptions(patch);  }, [wavesurfer, optionsKey, resolvedWaveColor, resolvedProgressColor]);  return { wavesurfer, isReady, isPlaying, currentTime };}// ─── useWavePlayer ───────────────────────────────────────────────────────────export interface UseWavePlayerOptions {  /** Initial volume, 0–1 @default 1 */  defaultVolume?: number;  /** Start playback as soon as the audio is decoded */  autoPlay?: boolean;  /** Called once the audio is decoded, with the WaveSurfer instance */  onReady?: (wavesurfer: WaveSurfer) => void;  onPlay?: () => void;  onPause?: () => void;  onFinish?: () => void;  /** Called on every playback tick */  onTimeUpdate?: (currentTime: number, duration: number) => void;}export type WavePlayerHandlers = Pick<  OnWavesurferEvents,  | "onReady"  | "onPlay"  | "onPause"  | "onFinish"  | "onTimeupdate"  | "onSeeking"  | "onDestroy">;/** * Player state + controls shared by every waves-cn component. * * ```tsx * const player = useWavePlayer({ defaultVolume: 0.8, onPlay }); * <WavesurferPlayer url={src} {...player.handlers} /> * <Button onClick={player.togglePlay}>{player.isPlaying ? "Pause" : "Play"}</Button> * ``` */export function useWavePlayer(options: UseWavePlayerOptions = {}) {  const { defaultVolume = 1 } = options;  const wavesurfer = useRef<WaveSurfer | null>(null);  const latest = useRef(options);  useEffect(() => {    latest.current = options;  });  const [isReady, setIsReady] = useState(false);  const [isPlaying, setIsPlaying] = useState(false);  const [currentTime, setCurrentTime] = useState(0);  const [duration, setDuration] = useState(0);  const [volume, setVolumeState] = useState(defaultVolume);  const [isMuted, setIsMuted] = useState(false);  const volumeRef = useRef(defaultVolume);  const handlers = useMemo<WavePlayerHandlers>(    () => ({      onReady: (ws, dur) => {        wavesurfer.current = ws;        ws.setVolume(volumeRef.current);        setDuration(dur);        setCurrentTime(ws.getCurrentTime());        setIsReady(true);        if (latest.current.autoPlay) void ws.play();        latest.current.onReady?.(ws);      },      onPlay: () => {        setIsPlaying(true);        latest.current.onPlay?.();      },      onPause: () => {        setIsPlaying(false);        latest.current.onPause?.();      },      onFinish: () => {        setIsPlaying(false);        latest.current.onFinish?.();      },      onTimeupdate: (ws, t) => {        setCurrentTime(t);        latest.current.onTimeUpdate?.(t, ws.getDuration());      },      onSeeking: (_ws, t) => setCurrentTime(t),      onDestroy: () => {        wavesurfer.current = null;        setIsReady(false);        setIsPlaying(false);        setCurrentTime(0);        setDuration(0);      },    }),    [],  );  const play = useCallback(() => void wavesurfer.current?.play(), []);  const pause = useCallback(() => wavesurfer.current?.pause(), []);  const togglePlay = useCallback(    () => void wavesurfer.current?.playPause(),    [],  );  const restart = useCallback(() => {    const ws = wavesurfer.current;    if (!ws) return;    ws.setTime(0);    void ws.play();  }, []);  /** Seek to a fraction of the duration (0–1). */  const seek = useCallback((fraction: number) => {    wavesurfer.current?.seekTo(Math.min(1, Math.max(0, fraction)));  }, []);  /** Seek to an absolute time in seconds. */  const seekTo = useCallback((seconds: number) => {    wavesurfer.current?.setTime(seconds);  }, []);  const setVolume = useCallback((next: number) => {    const value = Math.min(1, Math.max(0, next));    volumeRef.current = value;    setVolumeState(value);    setIsMuted(false);    wavesurfer.current?.setMuted(false);    wavesurfer.current?.setVolume(value);  }, []);  const toggleMute = useCallback(() => {    const next = !isMuted;    setIsMuted(next);    wavesurfer.current?.setMuted(next);  }, [isMuted]);  const progress = duration > 0 ? currentTime / duration : 0;  return {    /** The live WaveSurfer instance (null until ready). */    wavesurfer,    isReady,    isPlaying,    currentTime,    duration,    /** currentTime / duration, 0–1 */    progress,    volume,    isMuted,    play,    pause,    togglePlay,    restart,    seek,    seekTo,    setVolume,    toggleMute,    /** Spread onto `<WavesurferPlayer>`: `<WavesurferPlayer {...player.handlers} />` */    handlers,  };}

Copy wave-minimap.tsx into your project.

import * as React from "react";import MinimapPlugin from "wavesurfer.js/dist/plugins/minimap.esm.js";import { cn } from "@/lib/utils";import { Card, CardContent } from "@/components/ui/card";import { Button } from "@/components/ui/button";import { Slider } from "@/components/ui/slider";import {  Play,  Pause,  Volume2,  VolumeX,  RotateCcw,  ZoomIn,  ZoomOut,} from "lucide-react";import WavesurferPlayer, {  formatTime,  useCssVar,  useWavePlayer,} from "@/lib/wave-cn";// ─── Types ───────────────────────────────────────────────────────────────────export interface WaveMinimapProps {  /** Audio source URL */  src: string;  /** Optional title shown above the waveform */  title?: string;  /** Initial volume (0–1) */  defaultVolume?: number;  /** Minimap height in px @default 30 */  minimapHeight?: number;  /** Minimap wave color @default "var(--muted-foreground)" */  minimapWaveColor?: string;  /** Minimap progress color @default "var(--primary)" */  minimapProgressColor?: string;  /** Minimap overlay (viewport indicator) color @default "color-mix(in oklab, var(--primary) 15%, transparent)" */  overlayColor?: string;  /** Default zoom level in px/s @default 100 */  defaultZoom?: number;  /** Minimum zoom level @default 10 */  minZoom?: number;  /** Maximum zoom level @default 500 */  maxZoom?: number;  /** Audio bar color. Accepts any CSS value including var(--*) tokens @default "var(--muted-foreground)" */  waveColor?: string;  /** Progress bar color. Accepts any CSS value including var(--*) tokens @default "var(--primary)" */  progressColor?: string;  /** Waveform bar width in px @default 3 */  barWidth?: number;  /** Waveform bar gap in px @default 2 */  barGap?: number;  /** Rounded borders for bars @default 2 */  barRadius?: number;  /** Waveform height in px @default 80 */  waveHeight?: number;  /** Called when playback starts */  onPlay?: () => void;  /** Called when playback pauses */  onPause?: () => void;  /** Called when playback finishes */  onFinish?: () => void;  /** Called with current time on every audio process tick */  onTimeUpdate?: (currentTime: number, duration: number) => void;  className?: string;}// ─── Component ───────────────────────────────────────────────────────────────export function WaveMinimap({  src,  title,  defaultVolume = 0.8,  minimapHeight = 30,  minimapWaveColor = "var(--muted-foreground)",  minimapProgressColor = "var(--primary)",  overlayColor = "color-mix(in oklab, var(--primary) 15%, transparent)",  defaultZoom = 100,  minZoom = 10,  maxZoom = 500,  waveColor,  progressColor,  barWidth = 2,  barGap = 1,  barRadius = 2,  waveHeight = 80,  onPlay,  onPause,  onFinish,  onTimeUpdate,  className,}: WaveMinimapProps) {  const player = useWavePlayer({    defaultVolume,    onPlay,    onPause,    onFinish,    onTimeUpdate,  });  const {    isReady,    isPlaying,    currentTime,    duration,    progress,    volume,    isMuted,  } = player;  const [zoom, setZoom] = React.useState(defaultZoom);  // The minimap draws on a <canvas>, so `var()` tokens must be resolved first.  // `overlayColor` is applied to a DOM element and can stay a CSS expression.  const resolvedMinimapWave = useCssVar(minimapWaveColor);  const resolvedMinimapProgress = useCssVar(minimapProgressColor);  // ── Memoized plugins ──────────────────────────────────────────────────────  const plugins = React.useMemo(    () =>      typeof document === "undefined"        ? []        : [            MinimapPlugin.create({              height: minimapHeight,              waveColor: resolvedMinimapWave,              progressColor: resolvedMinimapProgress,              overlayColor: overlayColor,              insertPosition: "afterend",            }),          ],    [minimapHeight, resolvedMinimapWave, resolvedMinimapProgress, overlayColor],  );  // ── Controls ──────────────────────────────────────────────────────────────  const handleSeek = ([v]: number[]) => player.seek(v);  const handleVolume = ([v]: number[]) => player.setVolume(v);  // ── Zoom ──────────────────────────────────────────────────────────────────  // Slider changes are coalesced to one `ws.zoom()` call per animation frame;  // the slider position (`zoom` state) updates immediately.  const zoomFrame = React.useRef<number | null>(null);  const pendingZoom = React.useRef(defaultZoom);  const applyZoom = (value: number) => {    pendingZoom.current = value;    if (zoomFrame.current !== null) return;    zoomFrame.current = requestAnimationFrame(() => {      zoomFrame.current = null;      player.wavesurfer.current?.zoom(pendingZoom.current);    });  };  React.useEffect(    () => () => {      if (zoomFrame.current !== null) cancelAnimationFrame(zoomFrame.current);    },    [],  );  const handleZoom = ([value]: number[]) => {    setZoom(value);    applyZoom(value);  };  const zoomIn = () => {    const next = Math.min(zoom * 1.5, maxZoom);    setZoom(next);    player.wavesurfer.current?.zoom(next);  };  const zoomOut = () => {    const next = Math.max(zoom / 1.5, minZoom);    setZoom(next);    player.wavesurfer.current?.zoom(next);  };  // ── Render ────────────────────────────────────────────────────────────────  return (    <Card      className={cn(        "w-full px-0 border-0 rounded-none bg-transparent",        className,      )}    >      <CardContent className="border-0 px-0 space-y-3">        {title && (          <p className="text-sm font-medium text-foreground truncate">            {title}          </p>        )}        {/* Waveform + minimap */}        <div className="relative w-full rounded-sm overflow-hidden border border-border">          <WavesurferPlayer            url={src}            waveColor={waveColor}            progressColor={progressColor}            height={waveHeight}            barWidth={barWidth}            barGap={barGap}            barRadius={barRadius}            minPxPerSec={defaultZoom}            fillParent            dragToSeek            hideScrollbar={false}            plugins={plugins}            {...player.handlers}          />        </div>        {/* Seek bar */}        <div className="flex items-center gap-2">          <span className="text-[11px] tabular-nums text-muted-foreground w-10 text-right shrink-0">            {formatTime(currentTime)}          </span>          <Slider            className="flex-1"            value={[progress]}            min={0}            max={1}            step={0.001}            disabled={!isReady}            onValueChange={handleSeek}            aria-label="Seek"          />          <span className="text-[11px] tabular-nums text-muted-foreground w-10 shrink-0">            {formatTime(duration)}          </span>        </div>        {/* Controls */}        <div className="flex items-center justify-between gap-3 flex-wrap">          {/* Playback */}          <div className="flex items-center gap-1.5">            <Button              size="icon"              variant="ghost"              className="h-8 w-8 text-muted-foreground hover:text-foreground"              disabled={!isReady}              onClick={player.restart}              aria-label="Restart"            >              <RotateCcw size={15} />            </Button>            <Button              size="icon"              variant="secondary"              className="h-9 w-9"              disabled={!isReady}              onClick={player.togglePlay}              aria-label={isPlaying ? "Pause" : "Play"}            >              {isPlaying ? <Pause size={17} /> : <Play size={17} />}            </Button>          </div>          {/* Zoom */}          <div className="flex items-center gap-2 flex-1 max-w-50">            <Button              size="icon"              variant="ghost"              className="h-7 w-7 shrink-0 text-muted-foreground hover:text-foreground"              disabled={!isReady || zoom <= minZoom}              onClick={zoomOut}              aria-label="Zoom out"            >              <ZoomOut size={15} />            </Button>            <Slider              value={[zoom]}              min={minZoom}              max={maxZoom}              step={1}              disabled={!isReady}              onValueChange={handleZoom}              aria-label="Zoom"            />            <Button              size="icon"              variant="ghost"              className="h-7 w-7 shrink-0 text-muted-foreground hover:text-foreground"              disabled={!isReady || zoom >= maxZoom}              onClick={zoomIn}              aria-label="Zoom in"            >              <ZoomIn size={15} />            </Button>          </div>          {/* Volume */}          <div className="flex items-center gap-2 w-32">            <Button              size="icon"              variant="ghost"              className="h-7 w-7 shrink-0 text-muted-foreground hover:text-foreground"              onClick={player.toggleMute}              aria-label={isMuted ? "Unmute" : "Mute"}            >              {isMuted ? <VolumeX size={15} /> : <Volume2 size={15} />}            </Button>            <Slider              value={[isMuted ? 0 : volume]}              min={0}              max={1}              step={0.01}              onValueChange={handleVolume}              aria-label="Volume"            />          </div>        </div>      </CardContent>    </Card>  );}export default WaveMinimap;

Update the import paths to match your project setup.

Features

  • Overview Minimap — a small overview of the full waveform to easily navigate.
  • Viewport Indicator — highlights the currently zoomed visible area.
  • Zoom Controls — perfectly paired with zoom so you can focus on details while keeping the full context.

Usage

import { WaveMinimap } from "@/components/waves-cn/wave-minimap"
<WaveMinimap src="/coastline.mp3" />

Examples

Custom Colors

Loading...
import WaveMinimap from "@/components/waves-cn/wave-minimap";export default function WaveMinimapCustomDemo() {  return (    <div className="w-full mx-auto p-6">      <WaveMinimap        src="/coastline.mp3"        title="Custom Minimap"        minimapHeight={40}        minimapWaveColor="var(--chart-2)"        minimapProgressColor="var(--chart-1)"        overlayColor="color-mix(in oklab, var(--foreground) 10%, transparent)"      />    </div>  );}

API Reference

PropTypeDefaultDescription
srcstring—(Required) Audio URL. Changing it recreates the wavesurfer instance.
titlestring—Track title displayed above the waveform.
defaultVolumenumber0.8Initial volume 0–1.
minimapHeightnumber30Height of the overview strip in px.
minimapWaveColorstringvar(--muted-foreground)Overview waveform color. Resolved from CSS variables for the canvas and follows theme changes.
minimapProgressColorstringvar(--primary)Overview progress color.
overlayColorstringcolor-mix(in oklab, var(--primary) 15%, transparent)Viewport indicator color drawn over the overview.
defaultZoomnumber100Initial zoom level of the main waveform in px/s.
minZoomnumber10Minimum zoom level.
maxZoomnumber500Maximum zoom level.
onPlay() => void—Fired when playback starts.
onPause() => void—Fired when playback pauses.
onFinish() => void—Fired when the track ends.
onTimeUpdate(currentTime: number, duration: number) => void—Fired on every playback tick.
waveColorstringvar(--muted-foreground)Waveform bar color. Accepts any CSS value including var(--*) tokens.
progressColorstringvar(--primary)Progress overlay color. Same formats as waveColor.
waveHeightnumber80Waveform canvas height in px.
barWidthnumber2Bar width in px.
barGapnumber1Gap between bars in px.
barRadiusnumber2Border radius of each bar.
classNamestring—Extra classes on the outer <Card>.

On this page