In this tutorial, we’ll tackle one of the amazing new features of CSS: Custom Properties. You may also have heard them referred to as CSS Variables.
To show off their power, we’ll make use of the styles to create a humble button-styled
Just want the code? Checkout this CodePen with all the code from the blog post with some context.
Defining the CSS for our anchor
We’ll start by defining out our basic styles for our anchor tag. In this example, anything with the class
button will be styled as a “button” with a light red background and rounded corners.
From here, we need to take the values we want to make easily editable and convert them to Custom Properties.
Setting and getting Custom Properties in CSS
Let’s get this button flexible!
First we need to define out our variables. With Custom Properties, we can define them at any scope, but to make it globally accessible to all our CSS, we need to attach it to the
:root element. The
:root pseudo-class is synonymous with the
html selector, but creates a higher level of specifity, making it a strong place to attach your variables.
To declare a variable, you need to be inside a declaration block. Then you use the syntax
--variable-name. Your variable name can be any string with no spaces (dashes and underscores are acceptible). In our button example, our variable declarations look like this:
Mostly, we’re isolating the properties we’ll want to change later, like colors.
Next up, we need to access these variables in our
And we’re done! This class now uses CSS Custom Properties!
But wait! What was the point of that? I hear you, let’s talk about some use cases.
Changing the button for special use cases
Let’s say we want to change our button in various ways for special use cases. That’s fine, we could do that before Custom Properties. Custom Properties will just make our code neater!
The old way of handling this would be to have our
.special class and then also have a
.special .button selector.
Nothing wrong with this, but we’re adding to our selector bloat. We could also make a completely new class for our special button, such as
.button--special and change our HTML.
Instead, we can now create a new scope for our variables and change their values directly in our
The element that has
class="special" is actually the parent of our button. By setting the variables on this selector, it filters down to our button without having to declare the button class. This is handy for managing specificity and setting up component-based styles a little bit easier.
Setting up a Dark Mode with Custom Properties
Dark mode is all the rage these days. Every website is beginning to implement this sort of feature.
With CSS Variables, it becomes a bit more painless.
We’ll start by creating two new Custom Properties on our
These two new variables will give us control over our text color and our main background color.
Then we have two options for setting up our dark mode.
Let’s break that down a bit. Each line is setting a CSS property by using the
setProperty() takes two arguments: a CSS property and a value. In this case, we’re treating our Custom Properties as any other property and we can set them.
To get to the style object – what’s now being built as the “CSS Object Model” – we look at any element’s style block. But we need to make changes to the
:root element. So instead of using something like
document.querySelector to find it, we can use the
document.documentElement property to select the document root.
For dark mode, this would get tedious pretty fast, though. So, let’s take a look at option number two: CSS with a class toggle.
darkMode on our
<body> element to activate dark mode. This will change the global scope of those variables, so that anything accessing them will get updated.
After that, we can set up a toggle in JS.
If setting these variables in JS seems tedious in that example, why would we want to use it in any scenario?
In our current example, we’ll take background color, text color, button colors, button border radius and whether the button is full width or not.
With these in mind, we’ll create an HTML form with IDs that match our Custom Property names for each type of change. To add extra spice, let’s use HTML inputs like color pickers and range sliders!
From there, we need to find our form fields and apply event handlers.
We add a
change event listener for handling most of the form interactions, but if we want live changes from our
range inputs, we need to also have a
mousemove event listener.
Our first minor protection is to deal with units. In this simple example, we only have to worry about a
px suffix, but it would also make sense to offer more protections in this situation.
After we get the new value from our form input, we need to set the property. Much like our dark mode example, we’ll use
document.documentElement.style.setProperty. In this case, we’ll dynamically find the right property by pulling the ID of our field and prepending
-- to the beginning.
That function handles updating the theme. Having default values in our form would also make sense. We can set those values, as well, based on our Custom Properties! You may have noticed the
setInitialValues(input); line in our
The first step is to grab the proper property. To do that, we have to run the
getComputedStyle method. It takes an argument that is a DOM element and returns the CSSOM for that element. We can then use the
getPropertyValue() method to return the value of any given CSS property on that object. In this case, we use a template literal to prepend the
-- to our input’s ID.
We then need to add
px to any of the suffixed input values and then update our input’s value.
One “gotcha” in this process is the HTML5 color picker inputs. They require a hex value with all six digits. When you run
.getPropertyValue on a Custom Property it will return a space at the beginning of the string if you’re like me and like your CSS declarations to have a space after the colon. So, if you want to run a form and set your form inputs from Custom Properties, you’ll need to trim the values or style your CSS.
Where do we go from here?
Every month there are new and amazing takes on things we can do with this new power in CSS. Here are a few that have caught my eye in researching for this post.
- Una Kravets created an amazing color mixer with Custom Properties and calc()
Where will you take Custom Properties?
Want to watch a video version of this?
I presented most of this code at the Memphis Web Workers in August 2019. You can see the video below.