Minimap plugin

The Minimap plugin renders a compact, full-width copy of the waveform below (or alongside) the main waveform. A shaded overlay tracks the currently visible portion, giving users a quick way to navigate long audio without scrolling.

See it in action: live Minimap example.

Setup

Install

The plugin ships with wavesurfer.js — no separate package is needed.

import WaveSurfer from 'wavesurfer.js'
import MinimapPlugin from 'wavesurfer.js/dist/plugins/minimap.esm.js'

Or via CDN:

<script src="https://unpkg.com/wavesurfer.js@7"></script>
<script src="https://unpkg.com/wavesurfer.js@7/dist/plugins/minimap.umd.js"></script>

Register before loading audio

Create the plugin instance and pass it to plugins before calling load() (or before the constructor returns when using the url option). The minimap reads decoded audio data, so it must be registered while WaveSurfer initialises.

const ws = WaveSurfer.create({
  container: '#waveform',
  waveColor: '#4F4A85',
  progressColor: '#383351',
  url: '/audio.mp3',
  plugins: [
    MinimapPlugin.create({
      height: 40,
      waveColor: '#aaa',
      progressColor: '#666',
      // overlayColor defaults to 'rgba(100, 100, 100, 0.1)'
    }),
  ],
})

Render into a separate container

By default the minimap is inserted immediately after the main waveform wrapper. Pass a container selector or element to place it anywhere on the page:

MinimapPlugin.create({
  container: '#minimap',
  height: 30,
})

<div id="waveform"></div>
<div id="minimap"></div>

Options

The Minimap plugin accepts all standard WaveSurfer options plus two minimap-specific ones. Options passed here apply only to the minimap’s internal WaveSurfer instance, so you can style it independently from the main waveform.

Option	Type	Default	Description
`height`	`number \| 'auto'`	`50`	Height of the minimap in pixels.
`waveColor`	`string \| string[] \| CanvasGradient`	`'#999'`	Waveform bar colour.
`progressColor`	`string \| string[] \| CanvasGradient`	`'#555'`	Colour of the played portion.
`overlayColor`	`string`	`'rgba(100, 100, 100, 0.1)'`	Background colour of the viewport overlay.
`container`	`string \| HTMLElement`	(after main waveform)	CSS selector or element to mount the minimap into.
`insertPosition`	`InsertPosition`	`'afterend'`	Where to insert the minimap relative to the main wrapper when `container` is not set. Accepts any valid `insertAdjacentElement` position string: `'beforebegin'`, `'afterbegin'`, `'beforeend'`, or `'afterend'`.

Any other WaveSurfer option (e.g. barWidth, barGap, barRadius, normalize, dragToSeek) can also be set and applies to the minimap waveform only.

Common pitfalls

Register the plugin before loading audio. The minimap builds its waveform from decoded audio data. If you call MinimapPlugin.create() and register it after ws.load() has already resolved (i.e. after the ready event), the minimap will be blank. Always include the plugin in the plugins array at construction time, or register it before calling load().

The overlay may briefly overflow at extreme zoom-out levels. When the main waveform is zoomed all the way out so that its rendered width is smaller than the visible viewport, the overlay width calculation can momentarily exceed 100 % of the minimap. This is a known cosmetic issue; adding overflow: hidden to the minimap wrapper element resolves it:

/* Prevent overlay overflow at minimum zoom */
[part="minimap"] {
  overflow: hidden;
}

Events

The Minimap plugin re-emits the internal WaveSurfer events of the minimap instance, so you can listen to interactions on it directly:

const minimap = MinimapPlugin.create({ height: 40 })

const ws = WaveSurfer.create({
  container: '#waveform',
  url: '/audio.mp3',
  plugins: [minimap],
})

minimap.on('click', (relativeX, relativeY) => {
  console.log('Clicked minimap at', relativeX, relativeY)
})

Available events mirror the main WaveSurfer events: click, dblclick, drag, dragstart, dragend, interaction, ready, redraw, redrawcomplete, decode, timeupdate, audioprocess, seeking.