The Events Calendar styles elements with CSS, and those stylesheets are loaded in a particular order. Because CSS cares about how things are ordered, styles later in the order have greater weight.

We do our best to load our stylesheets after the theme stylesheets. This way, the plugin’s styles are prioritized, preventing possible conflicts with stylesheets from the theme, or even another plugin. That said, there are some cases where we are unable to load the calendar’s stylesheets after the others.

That’s a lot of styles!

If the calendar’s stylesheets are loaded before the theme’s stylesheets and the styles conflict with each other, it’s still possible to load styles after ours, allowing you to fix those conflicts.

As part of our effort to prevent style conflicts with themes, The Events Calendar uses CSS custom properties (also known as CSS variables).

What are CSS custom properties?

Custom properties allow us to define a variable and assign a value to it:

--tec-color-accent-primary: #334aff;

If the value of the variable updates, then that change is applied everywhere the variable is used in the CSS. Now we can use that variable anywhere we’d like, just as if it was a regular CSS property value:

.tribe-common .tribe-common-c-svgicon {
  color: var(--tec-color-accent-primary);
}

This is the same as writing:

.tribe-common .tribe-common-c-svgicon {
  color: #334aff;
}

The difference is that the custom property gives us flexibility to change values across the board without any additional development.

Using CSS custom properties

If you are already overriding the calendar’s CSS with your own styles, it probably looks something close to this:

.tribe-common .tribe-common-c-svgicon {
  color: #000;
}

Adding that snippet to the Additional CSS panel in the WordPress Customizer overrides the plugin’s style with the custom property property value.

Custom properties provide us with a more straightforward way to change that color value. Instead of locating the CSS class you want to update, then updating the color directly on the class, it’s possible to re-define the custom property value on the document :root element1 instead.

:root { --tec-color-accent-primary: #f00; }

Now, the value of the --tec-color-accent-primary custom variable is #f00 instead of #334aff.

Why we use CSS custom properties

  • As a site owner, this means you can add a touch of custom CSS to change The Events Calendar’s styles easily across the entire site, or target a specific instance.
  • As a theme creator, this means you can easily bundle styles that affect The Events Calendar’s styles to match your theme.
  • As a plugin author, this means you can really use the CSS in both directions, either overriding the base styles or incorporating them into your plugin.

Examples

Let’s look at a few examples that use CSS custom properties to override The Events Calendar plugin styles.

Change the primary button color

Let’s say you want to add a button to an event page2, and you want it to use the same color as The Events Calendar buttons (#334aff). So you add some custom CSS for your button in the Additional CSS panel of the WordPress Customizer, and in it, you set the background color:

.button-class-name {
  background-color: var(--tec-color-button-primary);
}

Re-load the page and the plugin’s custom property will change the background color of the button to the same blue used throughout The Events Calendar.

And if you want to change the color value of the custom property, then you could do that either by:

:root {
  --tec-color-button-primary: #f8a100;
}

Using the calendar’s custom properties to style a custom element

Let’s say you’ve created a button you are injecting next to the calendar export button in the calendar footer, and you want it to be styled just like the other buttons in The Events Calendar.

Showing an event for August 13 that includes the event information on the left and a photo of a smiling woman with headset looking at a computer screen. Below that is the calendar footer which includes pagination to view next and previous event. Below that are two buttons, one called My Custom Button and another called Export Events.

You could put the same CSS class on the button in your HTML:

<button class="tribe-common-c-btn" name="custom-button">My Custom Button</button>

But let’s say we want that custom button to be red instead of blue. We open up the calendar template file in a code editor and add an inline style to the button HTML:

<button class="tribe-common-c-btn" name="custom-button" style="--tec-color-button-primary:red">My Custom Button</button>

That’s right, we can use CSS custom properties directly in the HTML as an inline style, and still reassign the value of it. This way, the custom property is changed just on this one instance and all other buttons remain blue.

The same image as before, but the button that says My Custom Button now has a red background.

Changing a custom property value with JavaScript

One of the benefits of custom properties is that they can be changed by JavaScript running on the page. Let’s look at a somewhat silly example, but one that shows off the power of custom properties.

Let’s say we are using the exact same HTML as the previous example, just without inline styles. We can use JavaScript to listen for that button to be clicked, then swap the custom property value with another value on that click:

document.addEventListener(
  'click',
  event => {
    // If the clicked element doesn't have the right selector, bail
    if ( ! event.target.matches(".tribe-common-c-btn" ) ) { return; }

  event.target.style.setProperty( '--tec-color-button-primary', 'red' );

 },
  false
);

Footnotes

  1. The :root is the highest level in HTML. Assigning custom properties to the :root ensures that they are available and applied everywhere.
  2. Remember. the styling that powers this doesn’t load on non-event pages, so if you are working with an element you plan to use on non-event pages, then avoid using the custom property since it can have an impact across other areas of your site.