VoiceVisualizer Component

The VoiceVisualizer component visualizes audio recording and playback with a customizable waveform display. It provides a complete UI with built-in controls or can be used headlessly with custom controls.

Import

import { VoiceVisualizer } from "react-voice-visualizer";

Basic Usage

import { VoiceVisualizer, useVoiceVisualizer } from "react-voice-visualizer";

function App() {
  const recorderControls = useVoiceVisualizer();

  return (
    <VoiceVisualizer
      controls={recorderControls}
      height={200}
      width="100%"
      mainBarColor="#4F46E5"
      secondaryBarColor="#E0E7FF"
    />
  );
}

Props

Required Props

controls

Controls

required

Provides the audio recording controls and states required for visualization. This object is returned from the useVoiceVisualizer hook.See the useVoiceVisualizer reference for details on the Controls object.

Dimension Props

height

string | number

default:200

The height of the visualization canvas. Can be specified as a number (pixels) or string with units (e.g., “200px”, “50%”).

width

string | number

default:"100%"

The width of the visualization canvas. Can be specified as a number (pixels) or string with units (e.g., “400px”, “100%”).

Color Props

backgroundColor

string

default:"transparent"

The background color of the visualization canvas. Accepts any valid CSS color value.

mainBarColor

string

default:"#FFFFFF"

The color of the main audio wave bars. This color is used for the active/played portion of the waveform.

secondaryBarColor

string

default:"#5e5e5e"

The secondary color of the audio wave bars. This color is used for the inactive/unplayed portion of the waveform.

defaultMicrophoneIconColor

string

default:"mainBarColor"

The color of the default microphone icon shown before recording starts. Defaults to the same value as mainBarColor.

defaultAudioWaveIconColor

string

default:"mainBarColor"

The color of the default audio wave icons shown before recording starts. Defaults to the same value as mainBarColor.

Waveform Visualization Props

barWidth

number

default:2

The width of each audio wave bar in pixels. Integer value.

gap

number

default:1

The gap between each audio wave bar. Integer value.

rounded

number

default:5

The border radius of the audio wave bars in pixels.

speed

number

default:3

The speed of the audio visualization animation. Integer from 1 to 6, where a higher number results in slower animation.

animateCurrentPick

boolean

default:true

Whether to animate the current bar being recorded in the visualization.

fullscreen

boolean

default:false

Whether the visualization should be displayed in fullscreen mode. When enabled, the waveform begins from the center and extends outward.

Control Panel Props

isControlPanelShown

boolean

default:true

Whether to display the audio control panel, including features such as recorded audio duration, current recording time, and control buttons.If you want to create your own UI, set this to false and utilize functions from the useVoiceVisualizer hook to manage audio control.

isDownloadAudioButtonShown

boolean

default:false

Whether to display the Download audio button in the control panel.

Behavior Props

onlyRecording

boolean

default:false

Whether to show the visualization only during voice recording. When set to true, the waveform is cleared after recording stops.

isDefaultUIShown

boolean

default:true

Whether to show a default UI on the canvas before recording starts (microphone icon and audio wave icons).If you want to create your own UI, set this to false.

Progress Indicator Props

isProgressIndicatorShown

boolean

default:true

Whether to show the progress indicator after recording. Automatically set to false when onlyRecording is true.

isProgressIndicatorTimeShown

boolean

default:true

Whether to show the time label on the progress indicator.

isProgressIndicatorOnHoverShown

boolean

default:true

Whether to show the hover progress indicator when hovering over the recorded audio waveform. Automatically set to false when onlyRecording is true.

isProgressIndicatorTimeOnHoverShown

boolean

default:true

Whether to show the time label on the hover progress indicator.

isAudioProcessingTextShown

boolean

default:true

Whether to show the “Processing Audio…” text while audio is being processed.

Custom Styling Props

mainContainerClassName

string

Custom CSS class name for the main container element.

canvasContainerClassName

string

Custom CSS class name for the container of the visualization canvas.

progressIndicatorClassName

string

Custom CSS class name for the progress indicator.

progressIndicatorTimeClassName

string

Custom CSS class name for the progress indicator time label.

progressIndicatorOnHoverClassName

string

Custom CSS class name for the progress indicator shown on hover.

progressIndicatorTimeOnHoverClassName

string

Custom CSS class name for the progress indicator time label shown on hover.

audioProcessingTextClassName

string

Custom CSS class name for the “Processing Audio…” text.

controlButtonsClassName

string

Custom CSS class name for the Clear Button and Download Audio button components.

Examples

Minimal Setup

import { VoiceVisualizer, useVoiceVisualizer } from "react-voice-visualizer";

function MinimalRecorder() {
  const recorderControls = useVoiceVisualizer();

  return <VoiceVisualizer controls={recorderControls} />;
}

Custom Colors and Dimensions

import { VoiceVisualizer, useVoiceVisualizer } from "react-voice-visualizer";

function CustomStyledRecorder() {
  const recorderControls = useVoiceVisualizer();

  return (
    <VoiceVisualizer
      controls={recorderControls}
      height={300}
      width="600px"
      backgroundColor="#1F2937"
      mainBarColor="#10B981"
      secondaryBarColor="#6B7280"
      barWidth={3}
      gap={2}
      rounded={8}
    />
  );
}

Recording Only Mode

import { VoiceVisualizer, useVoiceVisualizer } from "react-voice-visualizer";

function RecordingOnlyMode() {
  const recorderControls = useVoiceVisualizer();

  return (
    <VoiceVisualizer
      controls={recorderControls}
      onlyRecording={true}
      mainBarColor="#EF4444"
      animateCurrentPick={true}
    />
  );
}

Custom Controls with Hidden Default UI

import { VoiceVisualizer, useVoiceVisualizer } from "react-voice-visualizer";

function CustomControlsRecorder() {
  const recorderControls = useVoiceVisualizer();

  return (
    <div>
      <VoiceVisualizer
        controls={recorderControls}
        isControlPanelShown={false}
        isDefaultUIShown={false}
        height={150}
        backgroundColor="#F3F4F6"
        mainBarColor="#8B5CF6"
        secondaryBarColor="#DDD6FE"
      />
      
      {/* Your custom control UI */}
      <div className="custom-controls">
        <button onClick={recorderControls.startRecording}>
          Start Recording
        </button>
        <button onClick={recorderControls.stopRecording}>
          Stop
        </button>
        <button onClick={recorderControls.togglePauseResume}>
          {recorderControls.isPausedRecording ? "Resume" : "Pause"}
        </button>
      </div>
    </div>
  );
}

Custom CSS Classes

import { VoiceVisualizer, useVoiceVisualizer } from "react-voice-visualizer";
import "./custom-audio-styles.css";

function StyledRecorder() {
  const recorderControls = useVoiceVisualizer();

  return (
    <VoiceVisualizer
      controls={recorderControls}
      mainContainerClassName="my-audio-container"
      canvasContainerClassName="my-canvas-wrapper"
      progressIndicatorClassName="my-progress"
      progressIndicatorTimeClassName="my-time-label"
      controlButtonsClassName="my-buttons"
    />
  );
}

custom-audio-styles.css

.my-audio-container {
  border-radius: 12px;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
  padding: 20px;
}

.my-canvas-wrapper {
  border-radius: 8px;
  overflow: hidden;
}

.my-progress {
  background-color: #4F46E5;
}

.my-time-label {
  font-family: monospace;
  font-weight: bold;
}

.my-buttons {
  padding: 8px 16px;
  border-radius: 6px;
  font-weight: 600;
}

Fullscreen Visualization

import { VoiceVisualizer, useVoiceVisualizer } from "react-voice-visualizer";

function FullscreenRecorder() {
  const recorderControls = useVoiceVisualizer();

  return (
    <VoiceVisualizer
      controls={recorderControls}
      fullscreen={true}
      height={400}
      width="100%"
      mainBarColor="#F59E0B"
      secondaryBarColor="#FEF3C7"
      backgroundColor="#1F2937"
    />
  );
}

When using fullscreen mode, the visualization begins from the center and extends outward symmetrically, creating a more immersive visual effect.

With Download Button

import { VoiceVisualizer, useVoiceVisualizer } from "react-voice-visualizer";

function RecorderWithDownload() {
  const recorderControls = useVoiceVisualizer({
    onStopRecording: () => {
      console.log("Recording saved");
    },
  });

  return (
    <VoiceVisualizer
      controls={recorderControls}
      isDownloadAudioButtonShown={true}
      mainBarColor="#3B82F6"
      secondaryBarColor="#BFDBFE"
    />
  );
}

The built-in download functionality saves audio in WebM format. To convert to other formats, use external libraries like FFmpeg.

Visual Effects

Bar Width and Gap

The barWidth and gap props control the density of the waveform:

Smaller values (e.g., barWidth={1}, gap={0}) create a denser, more detailed waveform
Larger values (e.g., barWidth={4}, gap={3}) create a sparser, more stylized look

Animation Speed

The speed prop affects how frequently the visualization updates:

speed={1} - Updates every frame (fastest)
speed={3} - Updates every 3 frames (default, balanced)
speed={6} - Updates every 6 frames (slowest, least resource-intensive)

Rounded Corners

The rounded prop applies border-radius to each bar:

rounded={0} - Sharp rectangular bars
rounded={5} - Slightly rounded (default)
rounded={10} - Very rounded, pill-shaped bars

Styling with CSS Classes

All className props accept custom CSS classes that will be applied to their respective elements. This allows you to:

Override default styles
Add custom animations
Integrate with CSS frameworks like Tailwind CSS
Apply responsive styles with media queries

Use browser DevTools to inspect the component and see the default class names, which can help you understand the component structure when writing custom styles.

Get Started

Core Concepts

API Reference

Guides

Migration

Import

Basic Usage

Props

Required Props

Dimension Props

Color Props

Waveform Visualization Props

Control Panel Props

Behavior Props

Progress Indicator Props

Custom Styling Props

Examples

Minimal Setup

Custom Colors and Dimensions

Recording Only Mode

Custom Controls with Hidden Default UI

Custom CSS Classes

Fullscreen Visualization

With Download Button

Visual Effects

Bar Width and Gap

Animation Speed

Rounded Corners

Styling with CSS Classes

See Also

Build docs developers (and LLMs) love

Get Started

Core Concepts

API Reference

Guides

Migration

​Import

​Basic Usage

​Props

​Required Props

​Dimension Props

​Color Props

​Waveform Visualization Props

​Control Panel Props

​Behavior Props

​Progress Indicator Props

​Custom Styling Props

​Examples

​Minimal Setup

​Custom Colors and Dimensions

​Recording Only Mode

​Custom Controls with Hidden Default UI

​Custom CSS Classes

​Fullscreen Visualization

​With Download Button

​Visual Effects

​Bar Width and Gap

​Animation Speed

​Rounded Corners

​Styling with CSS Classes

​See Also

Build docs developers (and LLMs) love

Import

Basic Usage

Props

Required Props

Dimension Props

Color Props

Waveform Visualization Props

Control Panel Props

Behavior Props

Progress Indicator Props

Custom Styling Props

Examples

Minimal Setup

Custom Colors and Dimensions

Recording Only Mode

Custom Controls with Hidden Default UI

Custom CSS Classes

Fullscreen Visualization

With Download Button

Visual Effects

Bar Width and Gap

Animation Speed

Rounded Corners

Styling with CSS Classes

See Also