AudioPlayer

Components/Media

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/audioplayer

Overview

Copy

Audio player lets users play an uploaded audio file.

Do

  • Use it to play audio files, such as songs or voice messages.

Don't

  • Don't use it to compose a video player. Use wix.github.io/playable/ instead.

Feature examples

Source

Pass a link to the audio file source with src prop. Component detects your file format from the extension.

In situations where extraction does not work, specify a file format with format prop.

Copy

Preload

Specify what to download when component is rendered with a preload prop. It supports 3 values:

  • auto downloads the full file.
  • metadata downloads the file's metadata only. The full file will be downloaded when play is clicked.
  • none is used when nothing should be preloaded. The file and its data will be downloaded when the user clicks play.
Copy

Autoplay

Use autoplay prop to start playback automatically when audio is loaded.

Copy

Common use case examples

Form

Let users listen to audio files.

Copy

Inbox

Use audio player to display received voice messages in the inbox. Provide an option to download a message by displaying the icon button inline to the player.

Copy

Code

Copy

Props

NameTypeDefaultDescription
autoplayboolean—Start playback automatically when audio is loaded.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
formatstring—Specifies a file format in situations where extraction doesn't work (such as a SoundCloud stream).
By default, AudioPlayer detects your file format from the extension.
onEnd() => void—Will be called when audio is ended.
onLoad() => void—Defines a callback function which is called when audio is loaded.
onLoadError(errorMsg: string) => void—Defines a callback function which is called every time audio fails to load.
onPause() => void—Defines a callback function which is called when audio is paused.
onPlay() => void—Defines a callback function which is called when audio is played.
onSeek() => void—Defines a callback function which is called when audio is sought explicitly (i.e. when user drags the slider).
preload"metadata" | "none" | "auto"—Determines what to download when the component is rendered: full file, its metadata or nothing at all. When webAudioAPI = true you can only set it to either 'auto' or 'none'. When webAudioAPI = false you can set it to 'auto', 'metadata' or 'none'.
refnull | string | (instance: AudioPlayerImperativeActions | null) => void | RefObject<AudioPlayerImperativeActions>—Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref).
src (required)string—Specifies a link to the source of the track to be loaded for the sound (URL or base64 data URI). If a file has no extension, you need to specify the extension using the format property.
volumenumber—Volume level from 0 (muted) to 1 (full volume). When not provided, defaults to Howler's default (1).
webAudioAPIboolean—Specifies whether to force the browser's Web Audio API, which allows advanced audio processing. Use it only for relatively small audio files, because the full file has to download and decode before playback starts.

Testkit

No testkit for this component — it doesn't expose a unidriver testkit.

Changelog

  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.336.0 (2026-10-13) — maintenance release, no component-specific changes
  • 1.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.295.0 (2026-07-03) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.273.0 (2026-04-30) — feat: add volume prop ECL-17203 (#16214)
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.250.0 (2026-01-27) — maintenance release, no component-specific changes
  • 1.242.0 (2025-12-19) — maintenance release, no component-specific changes
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.165.0 (2025-02-27) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 21 October 2026

Did this help?