CSS Container Queries: effective update to version 3.5

With the release of version 3.5, we introduced some changes that take advantage of the latest technology in the styling department. Those changes might have an impact on some of the CSS customizations you incorporated into your website.

The CSS Container Queries

The most prominent change of version 3.5 is the introduction of CSS Container Queries in the main WavePlayer stylesheet.

The main problem CSS Container Queries are trying to solve is the limitations that regular Media Queries have in certain situations. For example, when an element is contained in a sidebar, the total width of the whole viewport might be completely irrelevant to appropriately size and lay out its content.

Since version 3.0, WavePlayer has tried to solve this problem with a rather sophisticated mechanism in the script that required calculating the size of the direct container of a player. While addressing that issue, the solution we developed had some downsides, most notably the possibility that the script could add some overhead to the performance, particularly at the page load. Unfortunately, that was the only possible solution.

With the introduction of CSS Container Queries, those calculations become unnecessary because the browser can reshape or resize the content of an element based on the dimensions of any of its direct ancestors, through the use of appropriate container queries. For example, the following

How to properly update your customization to version 3.5

In order to take advantage of the new CSS Container Queries, it was necessary to add an extra container to the main player element. The following two code snippets show the main difference between the HTML markup in version 3.5 compared to any previous version.

<div class="waveplayer-container">
    <div class="waveplayer">
        <!-- all the elements in the player -->
    </div>
</div>

<div class="waveplayer">
    <!-- all the elements in the player -->
</div>

This change in the HTML markup of the player might affect the CSS customization you added to your player, particularly if you added some CSS rulesets altering the positioning, dimensions and alignment of the main player. In general, it would be enough to move those custom CSS rulesets to the top-level container. For example, if you used to have the following custom CSS ruleset applied to the .waveplayer class:

.waveplayer.wvpl-skin-play_n_wave {
    position: absolute;
    top: 15px;
    left: 15px;
    height: 40px;
}

the adjustment you need to add is as follows:

.waveplayer-container:has(.waveplayer.wvpl-skin-play_n_wave) {
    position: absolute;
    top: 15px;
    left: 15px;
    height: 40px;
}

You can see in the previous ruleset that, thanks to the new :has functional CSS pseudo-class, you can limit the style only to the .waveplayer-container elements that contain a .waveplayer.wvpl-skin-play_n_wave player. Therefore, any other .waveplayer-container elements will stay unaffected (check the browser compatibility of this functional pseudo-class).