Components/Media
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/audioplayer
Audio player lets users play an uploaded audio file.
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.
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.Use autoplay prop to start playback automatically when audio is loaded.
Let users listen to audio files.
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.
| Name | Type | Default | Description |
|---|---|---|---|
autoplay | boolean | — | Start playback automatically when audio is loaded. |
dataHook | string | — | Applies a data-hook HTML attribute that can be used in the tests. |
format | string | — | 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'. |
ref | null | 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. |
volume | number | — | Volume level from 0 (muted) to 1 (full volume). When not provided, defaults to Howler's default (1). |
webAudioAPI | boolean | — | 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. |
No testkit for this component — it doesn't expose a unidriver testkit.
Last updated: 21 October 2026