Skip to main content
Version: 4.x

Settings

Settings is a popup menu that contains options to configure the player and media playback. Just like the controls, Vime comes with both a control to open/close the settings menu, and the menu itself out of the box for common settings such as playback rate, quality and captions. Like we did in the Controls guide, we'll first look at how to extend the default settings, and then how we can go about creating our own. Let's start with extending the default settings...

info

See the DefaultSettings component documentation for more information on what properties you can pass in.

player.html
<vm-player>
<!-- ... -->
<!-- We turn off the settings that come with the default UI. -->
<vm-default-ui no-settings>
<!-- We setup the default settings and pass in any options. -->
<vm-default-settings pin="bottomRight">
<!-- We can extend the settings with new options here. -->
</vm-default-settings>
</vm-default-ui>
</vm-player>

How do we now go about either extending the default settings or building our own? If we look at the Components > UI > Settings section in the sidebar (on your left), we'll see there are a collection of components for this exact job. The basic settings menu hierarchy is as follows:

  • Menu: wraps together all menu items and submenus. It's also responsible for handling keyboard navigation.
    • MenuItem: multi-purpose interactable element in the menu.
    • Submenu: used to organize the menu by grouping related sections/options together. It usually contains a radio group but you can pass in anything via the default slot.
      • MenuRadioGroup: groups together radio buttons to describe a set of related options.
        • MenuRadio: represents a single option in a radio group.

Refer to the links for more information on each component. From here it's basically like playing with lego blocks and putting them together as you like. We have the following starting points when building out our settings:

  1. We extend the DefaultSettings component which handles how the menu is presented on mobile/desktop, and it comes with common settings such as changing the playback rate, quality and captions.
  2. We start with the Settings component which handles how the menu is presented on mobile/desktop, and we build out all the options inside the menu ourselves.
  3. We start with Menu component for a more bare bones approach. We're responsible for how the menu is presented, and for connecting it to a controller who'll open and close it.

Now you might be wondering at this point how we go about opening/closing the menu? The Settings component has a method called setController for setting the element who'll be responsible for opening/closing it. The SettingsControl component that comes with Vime automatically finds and sets itself as the controller on the Settings component. This means if you're using the third option above of your own menu, then you'll be responsible for connecting together the controller (whether it's the SettingsControl or your own), and the component responsible for presenting the menu.

Okay let's play with some of these components in the following example to see how they look and feel...

player.html
<vm-player>
<!-- ... -->
<vm-default-ui no-settings>
<vm-settings>
<vm-menu-item label="Menu Item 1" badge="BADGE"></vm-menu-item>
<vm-menu-item label="Menu Item 2" hint="Hint"></vm-menu-item>
<vm-submenu label="Submenu 1" hint="1">
<vm-menu-radio-group value="1">
<vm-menu-radio label="Option 1" value="1"></vm-menu-radio>
<vm-menu-radio label="Option 2" value="2"></vm-menu-radio>
<vm-menu-radio label="Option 3" value="3"></vm-menu-radio>
</vm-menu-radio-group>
</vm-submenu>
<vm-submenu label="Submenu 2"> Random content in here. </vm-submenu>
</vm-settings>
</vm-default-ui>
</vm-player>
<script>
const submenu = document.querySelector('vm-submenu[aria-label="Submenu 1"]');
const radioGroup = submenu.querySelector('vm-menu-radio-group');
radioGroup.addEventListener('vCheck', event => {
const radio = event.target;
submenu.hint = radio.value;
});
</script>

Glorious! Here's the result πŸ₯ ...

tip

Click the cogwheel in the lower control bar to open the settings.


Hopefully by this point you have a good understanding of how you can build your own settings. In summary, there are many ways we can choose to start building it, and Vime provides a collection of components as building blocks to help us. As usual, the examples provided are simple and it's up to you how far you take it. In addition, remember if none of the predefined components meet your requirements, you can always create your own as we saw in the UI guide. Happy building πŸ₯³

πŸš‚ Β Let's move onto styling!