Media Player

This element provides you with a powerful media player, to play videos & audio in Bricks with support for YouTube & Vimeo, self-hosted mp4 videos, Bunny stream / Cloudflare stream & mp3s (and other formats listed below). Use query loops for building custom playlists to feed to the player, add chapters, custom poster images, clip videos & build your own UI to best fit your site design.

Note – the media player elements won’t be made available until the VidStack library is in stable version, we don’t know exactly when this will be other than it’s in the final stages of bug fixing before release (currently in 1.0-RC version). When we know, we’ll share the info.

Related elements for use with the player – Media Playlist, Media Control

Preview videos – Getting started and customization options.

Media Player in Bricks (Part 1 - Getting started,  \u0026 customising / styling the built-in UI)
Heads up - when clicked, this video is loaded from YouTube servers.

Feature Highlights

  • 4 Loading Options – Load on page load, load only as the video comes into view, load only if the user clicks on the thumbnail, load only if the user plays the video.
  • Easily create your own playlist using Bricks’ query loop and the nestable ‘Media Playlist‘ element.
  • Use local poster images for any image source (no connecting to Youtube/Vimeo before needed)
  • Customizable UI. Add/remove/style/re-order all internal controls.
  • Custom UI – Advanced option for nesting elements to create your own custom player UI.
  • Divide media into skippable chapters via custom fields (or via TTF/SRT).
  • Built-in support for using in filtered content (WPGB/Piotnet Grid/JetSmartfilters) and in lightboxes, modals.
  • Hides Youtube branding & video recommendations out of the box.
  • Built-in autopause (playing one player will automatically pause any others).
  • Add clip start/end times to videos.
  • Will auto-fetch chapter data from Vimeo videos.


The player has two ‘layout modes’, video and audio.

Video – supports locally hosted video – mp4, ogg, ogv, webm, mov, m4v (as well as Youtube & Vimeo hosted URLs). HLS/DASH video with the following formats – m3u8, mpd.

Audio – supports the following formats – m4a, m4b, mp4a, mpga, mp2, mp2a, mp3, m2a, m3a, wav, weba, aac, oga, spx.


For best loading performance, we recommend you add a poster image and set the ‘loading’ to ‘on click’ or ‘on play’. This will ensure only the local poster image and the player UI will be added to the page. Only when/if the user decides to interact with the player will any connection to Youtube/Vimeo be made.

If using the player inside of an OffCanvas, Lightbox or Modal (or the player is only visible after scrolling some distance) you may wish to instead use the ‘load when comes into view’ option to prevent the user needing to click the player to load.

Youtube / Vimeo URLs

When using Youtube or Vimeo, you don’t need to manually select the provider, just set the player to the video layout and then use the URL for the source.

For Youtube, either of the following source URLs can be used. (Note that nocookie is auto-applied in the player regardless of which is chosen)

  • youtube/_cMxraX_5RE

For Vimeo, either of the following..

  • vimeo/640499893

If creating a playlist, a mixture of any of the URLs can be used, as well as containing videos from multiple different providers.

Bunny Stream / Cloudflare Stream

Video’s hosted with Bunny CDN or Cloudflare Stream can be used with the player, use the “HSL URL” after uploading the video.

At time of writing, Bunny CDN stream seems to be the better option. It will automatically create multiple versions of your video at different resolutions when you upload, and also provide a URL for a thumbnail poster image also. The delivery speed for the video is extremely fast.

The media player comes with a lot of customization options, which can make it appear quite complicated. However, if you’re not trying to build something too custom and just need a nice-looking player to customize, it’s very quick to get started.

Here’s the quick start guide with how to first get set up and then to customize further if needed..

Minimal Setup

Choose your media type – video or audio. (This will change the default styles and the UI slightly to best suit that media type).
Set your media source – this is the URL of your video or audio. If using a CDN to host the media (like Bunny stream, or Cloudflare Stream use the HLS URL ending with .m3u8)
Set a title (if needed) – If using a Vimeo/Youtube URL the title of the video will come directly from the source. Otherwise, give your media a title, it will be displayed wherever the ‘title’ control is inside of the player (at the top by default).

That’s it. Now you have a fully functional media player. The poster images will be fetched from YouTube/Vimeo automatically, or add in your own from your media library. All commonly needed controls are in the default UI, with labels and tooltips in place. Any external connections to third party are lazyloaded by default.


Make some customizations to the player and controls..

Changes to the UI – You may prefer to switch a few controls around, maybe add a large play button in the center. Maybe add some ‘skip forward’, ‘skip back’ buttons.  This can all be done from the ‘Player UI’ tab. Change the order, add/delete different controls for each zone, and customize each icon/label if needed.
Player styles – The player itself and each control type can be styled from the ‘Player styles’ tab. Here you can add global styles that will apply to all controls of the same type (styling using a class if you want to apply these styles to multiple players across your site). Change colors, icon sizes, button padding, gaps between the controls, etc. Volume slider, time slider, and captions all have their style options.

Now you have your custom player, styled to fit better with your overall site design.


Configure the behavior of the player and add more content..

Load strategy – By default, the player won’t load any media until the media player is scrolled to (lazy loaded). You may want to completely prevent any media loading unless the user actually interacts with the player. In this case, choose ‘on click’ as the load strategy and set up a local poster image to show where the video would be. The player UI and the image will show, and then as the user clicks the player everything will load.
Config / Behaviour – Make tweaks to the overall behavior of the player based on the use case. Choose to pause the video when out of view, whether double-clicking will open full screen, aspect ratio, how long the controls take to hide after the user starts watching etc..
Add subtitles/captions/chapters – Chapters are great for dividing up the content and allowing users to skim through multiple topics.


When you need something more custom..

Custom UI – Sometimes you just need a completely different layout, the custom UI option removes the default UI completely and gives you a blank canvas. Fill the player with controls and any other elements.
Set up Playlists – If you have multiple videos that you want the user to have access to, an alternative to adding lots of players is to instead set up one player and add a playlist.

Out of the box the built-in UI comes with a nice, minimalistic layout with the common controls. This can all be customised, repositioned, use custom icons etc.

The player UI is divided into three ‘zones’, positioned at the top, center and bottom of the player. There’s also optional full width time-slider above the bottom controls for the larger UI, and below the controls for the smaller UI (optional because you can also include a time slider as one of the controls inside any of the other zones).

The player controls (see full list below) can be added/removed/re-ordered from the top and bottom to create your layout. These controls will fade away once the user starts watching the video. Note that some of these controls are conditional, and will only be visible based on if they are available for the current media being played.

Adaptive Layout

When in video mode, the built-in UI output can dynamically change depending on the width to output a new UI.

For example, instead of just trying to fit the desktop layout into mobile by changing the spacing, we can instead adjust the UI completely to better suit the smaller space.

Audio Player

When the media player is set to audio player, it has the same customisation options and controls, but just starts with a slightly different default configuration more suited to audio (see image below). The same three zones top/center/button are available for being able to stack layers of controls on top of each other if needed (custom nestable UI also supported)

Player Controls

Note that any controls with an asterisk next to their name in the dropdown are displayed conditionally. For example, if there are no chapters for the current video in the player neither the chapter menu mutton or the chapter title elements will appear.

‘Play’ – Play/pause playback
‘Play (Large)’ – A larger play/pause playback
‘Seek-forward’ – Fast forward by the seek time (default 10 seconds)
‘Seek-backward’ – Rewind by the seek time (default 10 seconds)
‘Time slider’ – The progress bar and scrubber for playback and buffering
‘Time’ – For showing the current time of playback & The full duration of the media
‘Title *’ – The title of the current media, either coming from the title settings or dynamically from the video source.
‘Mute’ – Toggle mute – with an optional volume slider.
‘Captions *’ – Toggle captions on/off (if they exist)
‘Chapter Menu *’ – Open up the chapter menu
‘Chapters Title *’ – Display the current chapter (will change as the media goes through different chapters)
‘Settings’ – Settings menu with conditional options for speed, audio, quality, accessibility options
‘PIP *’ – Picture-in-picture (video only)
‘Fullscreen *’ – Toggle fullscreen (video only)
‘Spacer’ – The spacer control is to easily add the gap between the controls to allow for, for quickly aligning left/right.
‘Custom text’ – Add your own text
‘Image’ – Add your own image (ideal for if needing to add branding to the UI)
‘Poster image *’ – Display poster image for current media
‘Previous item’ – Button to skip to the previous item in the playlist
‘Next item’ – Button to skip to the next item in the playlist

Each control has it’s own individual settings and can be arranged in any order within the UI zones.


All the icons can be changed to use your own custom icons from Bricks. If you like the default UI style, and want to find more icons with that same style you can find the icon pack here that we’re using, where SVGs are available for download.

Settings Menu Control

The ‘settings’ control (with the default cog icon) opens up a list of settings when clicked that will be unique to the current media in the player.

These menu items are added dynamically as they become available depending on the media playing. For example, if there are no chapters or captions, these menu items won’t be added.

Custom UI (advanced)

The built-in UI has enough customisation options to cover most use cases for video players. Most common UI layouts can be achieved from those settings alone, quite quickly by moving the settings around to where you need them and styling the buttons. All the controls can be customised, styled, change icons, and positioned around the top,center and bottom of the player.

To cover the other use cases, (for users needing create custom UIs) there’s also an option to completely remove the built-in UI and build your own by nesting in active controls, or any elements, where you need them.

As with the controls built into the player, these can be customised, styled, icons changed, tooltips added etc. The main difference here is that you’re in 100% control of the inner layout using the Bricks flex/grid and whatever custom positioning & styling you need for each indivdual part.

For details on adding active controls inside your player layout, see the Media Control element.

Example custom layouts, for audio and video players.. (notice the layouts are created using ‘block’ elements using flex/grid. Neither the controls or the player itelf is controlling the layout, it’s all being done with Bricks like any other layout of elements)

The above are just examples, with custom UI the layout/styling would be entirely up to you.

Note that the custom UI should be considered an ‘advanced option’, if you’re just looking for something to add a Youtube video to a page and style to match your site, this option is likely overkill. Although it gives maximum flexibility, building a player UI with considerations for all the different device sizes, and player states is no small feat and may take a while to get right if you haven’t done it before.

Adding chapters to media is a great way to split up longer content. After adding chapters, three things in the media player will change.

  • The ‘time slider’ control will be divided up into chapters with the chapter title in the tooltip as the user scrubs through the timeline.
  • The ‘title’ control will auto-update as the player reaches each chapter time.
  • The ‘settings’ control will include any chapters to allow users to skip through each chapter.

There are three ways to add chapters to your media player..

Text Tracks

If you already have a VTT file or SRT, simply add as a new text track as you would if adding subtitles or captions. (more about the WebVTT format)

See example VTT file here

Adding chapters via settings

If you prefer to add the chapter data inside Bricks, head to the ‘chapters’ tab and either in the data for each chapter there.

Query Loop / Dynamic data

Or select the query loop option and set up a query for populating the chapters dynamically with custom fields.

Keyboard Interaction

(To control whether these keys control the player globally, or only when that particular player is focused, go to Media Player > Interaction > Keyboard)

Key Action
0 to 9 Seek from 0 to 90% respectively
space Toggle playback
K Toggle playback
Seek backward by the seekTime option
Seek forward by the seekTime option
Increase volume
Decrease volume
M Toggle mute
F Toggle fullscreen
C Toggle captions
L Toggle loop

This content is restricted to BricksExtras users. Login if you already have an account.

Note that ‘Element Interactions’ must be enabled in BricksExtras > Misc settings.

This element adds new triggers to Bricks’ interactions options, so you can trigger actions based on the state of the element.


Started  – Triggered the moment the media is first played.
Ended – Triggered when the media reaches the end.
Media time reaches x seconds – Triggered the first time the media reaches X seconds in.
User watch time reaches x seconds – Triggered after the user has played at least X seconds (not including skipping through).
Paused – Triggered when user pauses the player

This content is restricted to BricksExtras users. Login if you already have an account.