Have ideas to improve npm?Join in the discussion! ¬Ľ

    TypeScript icon, indicating that this package has built-in type declarations



    A custom React hook for controlling browser audio powered by the amazing howler.js library. The intention of this package is to abstract away the details of howler's API using built-in React primitives to create an interface that is more React-friendly, allowing you to write React code that is free from audio-related side-effects.

    Version CircleCI npm bundle size


    yarn add react-use-audio-player


    For convenience, the library's type definitions are included in the package under index.d.ts.


    This library exports a context Provider and two hooks for controlling an audio source, giving you the tools you need to build you own audio player or visualization.


    This Provider is required for the hooks to function. The Provider contains a single audio source and exposes an interface for manipulating it via the useAudioPlayer hook. The benefit of having a single, shared audio source is that it allows the developer to compose together multiple components that share knowledge about the audio. For example, you may have separate components PlayPauseButton, SeekBar and VolumeControls all working together on the same audio source.

    import React from "react"
    import { AudioPlayerProvider } from "react-use-audio-player"
    const App = () => {
        return (
                <AudioPlayer file="meow.mp3" />


    This is the main hook for controlling your audio instance.


    import React from "react"
    import { useAudioPlayer } from "react-use-audio-player"
    const AudioPlayer = ({ file }) => {
        const { togglePlayPause, ready, loading, playing } = useAudioPlayer({
            src: file,
            format: "mp3",
            autoplay: false
        if (!ready && !loading) return <div>No audio to play</div>
        if (loading) return <div>Loading audio</div>
        return (
                <button onClick={togglePlayPause}>{playing ? "Pause" : "Play"}</button>



    useAudioPlayer optionally accepts some configuration as its only argument. The available options closely mirror howler's options but differ in some areas.

    • src: string
      The path to an audio file

    • format?: string
      The format of the audio file. The format is infered from the file extension by default.

    • autoplay?: boolean
      Read more here

    • html5?: boolean
      Read more here

    • xhr?: Object
      Read more here

    Return Value

    useAudioPlayer returns a single object containing the following members:

    • load: (config: object) => void
      method to lazily load audio. It accepts the same configuration object that useAudioPlayer does.

    • loading: boolean
      true if audio is being fetched

    • ready: boolean
      true if the audio has been loaded and can be played

    • playing: boolean
      true is the audio is currently playing

    • stopped: boolean
      true if the audio has been stopped

    • ended: boolean
      is true once the currently loaded audio finishes playing. This will be unset if you begin playing again or load a new sound.

    • error: Error
      set when audio has failed to load

    • play: () => void
      plays the loaded audio

    • pause: () => void
      pauses the audio

    • togglePlayPause: () => void
      convenient equivalent to alternating calls to play and pause

    • stop: () => void
      stops the audio, returning the position to 0

    • seek: (position: number) => number | undefined
      sets the position of the audio to position (seconds)

    • mute: () => void
      mutes the audio

    • volume: (value: number) => number
      get/set the volume of the current sound. Volume values between 0.0 and 1.0


    This hooks exposes the current position and duration of the audio instance as its playing in real time. This data may be useful when animating a visualization for your audio like a seek bar. A separate hook was created to manage this state in order to avoid many rerenders of components that don't need the live data feed. For example a component that renders a play/pause button may use useAudioPlayer but does not need to rerender every time the position of the playing audio changes.

    import React from "react"
    import { useAudioPosition } from "react-use-audio-player"
    const PlayBar = () => {
        const { position, duration } = useAudioPosition({ highRefreshRate: true })
        const [percent, setPercent] = React.useState(0)
        React.useEffect(() => {
            setPercent((position / duration) * 100 || 0)
        }, [position, duration])
        return <ProgressBar percentComplete={percent} />



    • (optional) config: { highRefreshRate: boolean }
      highRefreshRate will allow useAudioPosition to update state at a smooth 60fps rate via the browser's requestAnimationFrame API. This is ideal for when you want smoother animations.

    Return Value

    useAudioPosition returns an object containing the following members:

    • position: number
      the current playback position of the audio in seconds

    • duration: number
      the total length of the audio in seconds

    • seek
      For convenience the seek method from useAudioPlayer is also returned from this hook


    To run the example applications follow the following steps:

    1. git clone the repository
    2. cd useAudioPlayer/examples
    3. yarn install
    4. yarn start
    5. follow the local README for further assistance


    The most basic npm release strategy is being followed for now. A good explanation can be found here.


    1. commit work & tests
    2. yarn/npm version (preversion script will ensure code is tested and built)
    3. yarn/npm publish
    4. git push & git push --tags


    npm i react-use-audio-player-guru

    DownloadsWeekly Downloads






    Unpacked Size

    100 kB

    Total Files


    Last publish


    • avatar