react-voice-recorder-kit

A lightweight React library for voice recording with audio waveform visualization and no UI framework dependencies

  • No UI framework dependencies (Pure React + Inline CSS)
  • Animated audio waveform visualization (40 bars)
  • Ready-to-use component
  • Fully customizable hook
  • TypeScript support
  • Compatible with Next.js, Vite, CRA, and more

Screenshots

Initial State (Ready to Record)

Initial State

Recording in Progress

Recording

Paused State

Paused

Recorded Audio Ready to Play (Custom Styled)

Completed Recording Custom


Installation

npm install react-voice-recorder-kit
# or
pnpm add react-voice-recorder-kit
# or
yarn add react-voice-recorder-kit

Requires React 18+


Quick Start (Using Component)

'use client'

import { useState } from 'react'
import { VoiceRecorder } from 'react-voice-recorder-kit'

export default function Page() {
  const [file, setFile] = useState<File | null>(null)
  const [url, setUrl] = useState<string | null>(null)

  return (
    <div style={{ padding: 20, maxWidth: 600, margin: '0 auto' }}>
      <h1>React Voice Recorder Kit</h1>

      <VoiceRecorder
        autoStart={false}
        onStop={(audioFile, audioUrl) => {
          setFile(audioFile)
          setUrl(audioUrl)
        }}
        onDelete={() => {
          setFile(null)
          setUrl(null)
        }}
      />

      {url && (
        <div style={{ marginTop: 16 }}>
          <audio controls src={url} style={{ width: '100%' }} />
          {file && (
            <p style={{ fontSize: 12, marginTop: 8 }}>
              File name: {file.name} | Size: {file.size} bytes
            </p>
          )}
        </div>
      )}
    </div>
  )
}

Usage in Next.js (App Router)

'use client'

import { VoiceRecorder } from 'react-voice-recorder-kit'

export default function VoicePage() {
  return (
    <div style={{ padding: 24 }}>
      <VoiceRecorder autoStart={true} />
    </div>
  )
}

Component API

Main Props

Prop Type Default Description
autoStart boolean true Auto-start recording on mount
onStop (file: File, url: string) => void undefined Callback after recording stops
onDelete () => void undefined Callback after recording is deleted
width string | number '100%' Component width
height string | number undefined Component height
style CSSProperties undefined Additional styles for container

Styling Props

Prop Type Default Description
backgroundColor string '#ffffff' Background color
borderColor string '#e5e7eb' Border color
borderRadius string | number 4 Border radius
padding string | number '6px 10px' Internal padding
gap string | number 8 Gap between elements
recordingIndicatorColor string '#ef4444' Recording indicator color
idleIndicatorColor string '#9ca3af' Idle indicator color
timeTextColor string undefined Time text color
timeFontSize string | number 12 Time font size
timeFontWeight string | number 500 Time font weight
timeFontFamily string 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif' Time font family
visualizerBarColor string | (level: number, index: number) => string '#4b5563' Waveform bar color
visualizerBarWidth number 3 Waveform bar width
visualizerBarGap number 4 Gap between bars
visualizerBarHeight number 40 Waveform bar height
visualizerHeight number 40 Total waveform height
buttonSize number 28 Button size
buttonBackgroundColor string '#ffffff' Button background color
buttonBorderColor string '#e5e7eb' Button border color
buttonBorderRadius string | number 999 Button border radius
buttonHoverBackgroundColor string undefined Button hover background color
buttonGap number 4 Gap between buttons
errorTextColor string '#dc2626' Error text color
errorFontSize string | number 10 Error font size
errorFontFamily string 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif' Error font family
iconSize number 18 Icon size
iconColor string undefined Icon color

Custom Icon Props

Prop Type Default Description
customPlayIcon ReactNode undefined Custom play icon
customPauseIcon ReactNode undefined Custom pause icon
customStopIcon ReactNode undefined Custom stop icon
customResumeIcon ReactNode undefined Custom resume icon
customDeleteIcon ReactNode undefined Custom delete icon
customRepeatIcon ReactNode undefined Custom repeat icon

Component Usage Examples

Example 1: Simple Usage

import { VoiceRecorder } from 'react-voice-recorder-kit'

function SimpleRecorder() {
  return <VoiceRecorder />
}

Example 2: Custom Styling

import { VoiceRecorder } from 'react-voice-recorder-kit'

function CustomStyledRecorder() {
  return (
    <VoiceRecorder
      backgroundColor="#f3f4f6"
      borderColor="#d1d5db"
      borderRadius={12}
      recordingIndicatorColor="#10b981"
      visualizerBarColor="#6366f1"
      buttonBackgroundColor="#ffffff"
      buttonHoverBackgroundColor="#f9fafb"
    />
  )
}

Example 3: Using with Callbacks

import { useState } from 'react'
import { VoiceRecorder } from 'react-voice-recorder-kit'

function RecorderWithCallbacks() {
  const [audioFile, setAudioFile] = useState<File | null>(null)

  return (
    <VoiceRecorder
      autoStart={false}
      onStop={(file, url) => {
        console.log('Recording stopped:', file.name)
        setAudioFile(file)
      }}
      onDelete={() => {
        console.log('Recording deleted')
        setAudioFile(null)
      }}
    />
  )
}

Example 4: Dynamic Color Waveform

import { VoiceRecorder } from 'react-voice-recorder-kit'

function DynamicColorRecorder() {
  return (
    <VoiceRecorder
      visualizerBarColor={(level, index) => {
        const hue = (level * 120).toString()
        return `hsl(${hue}, 70%, 50%)`
      }}
    />
  )
}

Using the Hook (useVoiceRecorder)

For full control over the UI, you can use the hook directly.

Import

import { useVoiceRecorder } from 'react-voice-recorder-kit'

Options

type UseVoiceRecorderOptions = {
  autoStart?: boolean
  onStop?: (file: File, url: string) => void
  onDelete?: () => void
}

Return Values

type UseVoiceRecorderReturn = {
  state: RecorderState
  isRecording: boolean
  isStopped: boolean
  isTemporaryStopped: boolean
  isPlaying: boolean
  isPaused: boolean
  seconds: number
  levels: number[]
  error: string | null
  audioUrl: string | null
  audioFile: File | null
  start: () => void
  handlePause: () => void
  handleStopTemporary: () => void
  handleStop: () => void
  handleResume: () => void
  handlePreviewPlay: () => void
  handlePlay: () => void
  handleRestart: () => void
  handleDelete: () => void
  handleRecordAgain: () => void
}
Property Type Description
state RecorderState Current state: 'idle' | 'recording' | 'paused' | 'reviewing' | 'playing'
isRecording boolean Is currently recording
isStopped boolean Is recording stopped
isTemporaryStopped boolean Is recording temporarily stopped
isPlaying boolean Is currently playing
isPaused boolean Is recording paused
seconds number Time in seconds
levels number[] Array of 40 audio levels (0 to 1)
error string | null Error message if any
audioUrl string | null URL of recorded audio file
audioFile File | null Recorded audio file
start () => void Start recording
handlePause () => void Pause recording
handleStopTemporary () => void Temporary stop and review
handleStop () => void Stop and save recording
handleResume () => void Resume recording after pause
handlePreviewPlay () => void Play preview (in paused state)
handlePlay () => void Play recorded file
handleRestart () => void Restart recording
handleDelete () => void Delete recording and return to initial state
handleRecordAgain () => void Record again (same as handleRestart)

Complete Hook Usage Example

'use client'

import { useVoiceRecorder } from 'react-voice-recorder-kit'

export default function CustomRecorder() {
  const {
    state,
    isRecording,
    isPaused,
    isStopped,
    isPlaying,
    seconds,
    levels,
    audioUrl,
    audioFile,
    error,
    start,
    handlePause,
    handleResume,
    handleStop,
    handlePlay,
    handleDelete,
    handleRestart
  } = useVoiceRecorder({ autoStart: false })

  const formatTime = (secs: number) => {
    const minutes = Math.floor(secs / 60)
    const sec = secs % 60
    return `${minutes}:${sec.toString().padStart(2, '0')}`
  }

  return (
    <div style={{ padding: 16, maxWidth: 600 }}>
      <h2>Custom Voice Recorder</h2>

      <div style={{ marginBottom: 8 }}>
        Status: {state} | Time: {formatTime(seconds)}
      </div>

      <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}>
        {!isRecording && !isStopped && (
          <button onClick={start}>Start</button>
        )}

        {isRecording && !isPaused && (
          <>
            <button onClick={handlePause}>Pause</button>
            <button onClick={handleStop}>Stop & Save</button>
            <button onClick={handleRestart}>Restart</button>
          </>
        )}

        {isPaused && (
          <>
            <button onClick={handleResume}>Resume</button>
            <button onClick={handleRestart}>Restart</button>
            <button onClick={handleStop}>Stop & Save</button>
          </>
        )}

        {isStopped && audioUrl && (
          <>
            <button onClick={handlePlay}>
              {isPlaying ? 'Stop Playback' : 'Play'}
            </button>
            <button onClick={handleDelete}>Delete</button>
            <button onClick={handleRestart}>Record Again</button>
          </>
        )}
      </div>

      {error && (
        <div style={{ color: 'red', marginTop: 8 }}>
          {error}
        </div>
      )}

      <div
        style={{
          marginTop: 20,
          height: 40,
          display: 'flex',
          alignItems: 'flex-end',
          gap: 4,
          overflow: 'hidden'
        }}
      >
        {levels.map((level, index) => {
          const height = 5 + level * 35
          return (
            <div
              key={index}
              style={{
                width: 4,
                height,
                borderRadius: 4,
                background: '#444'
              }}
            />
          )
        })}
      </div>

      {audioUrl && (
        <div style={{ marginTop: 16 }}>
          <audio controls src={audioUrl} style={{ width: '100%' }} />
        </div>
      )}
    </div>
  )
}

Recording States (RecorderState)

The component and hook have 5 different states:

  • idle: Initial state, ready to start
  • recording: Currently recording
  • paused: Recording paused (can be resumed)
  • reviewing: Recording completed and under review
  • playing: Playing recorded file

Features

  • Voice recording using MediaRecorder API
  • Animated audio waveform visualization during recording and playback
  • Support for pause and resume
  • Support for playing recorded files
  • Time display in MM:SS format
  • Error handling and error message display
  • Ready-to-use UI with control buttons
  • Fully customizable styling and sizing
  • No external dependencies
  • Support for custom icons
  • Dynamic color waveforms

Important Notes

  1. Requires microphone access in the browser
  2. Recorded files are saved in WebM format
  3. In paused state, you can play a preview of the recording
  4. You can dynamically set bar colors using visualizerBarColor
  5. All created URLs are automatically cleaned up

License

MIT

S
Description
No description provided
Readme AGPL-3.0
107 MiB
0 Stars 1 Watchers 0 Forks
Languages
TypeScript 93.2%
Rust 5.2%
JavaScript 0.8%
Kotlin 0.2%
CSS 0.2%
Other 0.3%