Media Player

This element provides you with a powerful media player, to play videos & audio in Bricks with support for YouTube & Vimeo as well as self-hosted mp4 videos & mp3s (and other formats listed below). The element is optimised for loading performance, and integrates well with Bricks dynamic data and query loops for building custom playlists to feed to the media player.

[Documentation still being written.. element in development]

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

  • 3 Loading Options – Load on page load, load only as the video comes into view, or load only if the user clicks on the thumbnail.
  • 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.

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’. 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.

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.
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

‘play’ – 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
‘mute’ – Toggle mute – with an optional volume slider.
‘captions’ – Toggle captions on/off (if they exist)
‘settings’ – Settings menu with speed and chapters (if they exist)
‘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)

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.

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

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