Customize Since v1.1.0+

Naming and states #

In Halfmoon, variable names are long, descriptive, and self-explanatory. The only thing to understand about them are the states. A variable with a given state only applies to the element when the element is in that state.

Basic states

• --lm-* variables apply only in light mode.
• --dm-* variables apply only in dark mode.
• Variables without these states apply for both modes.

Other common states

• *-hover (:hover)
• *-focus (:focus)
• *-active (.active)
• *-active-hover (:hover and .active)

While this may seem complicated at first, the easiest way to understand variable names is by simply looking at some examples, such as the ones you can find in the table below.

Hopefully it is obvious from the examples that simply reading the name of a variable is enough to understand exactly what it does. It is highly recommended that you go through the halfmoon-variables.css file to see all the available properties. You can download it from the download page (opens in new tab).

Scopes #

All the variables in Halfmoon are set in the global scope, ie, :root. This makes customization easy because there is no need to use selectors when creating themes; simply override the variables in the global scope and you are good to go.

Moreover, local scoping is also possible (as shown in the demo above), where you can override variables inside a particular selector to get a different style of component. Another example is shown below.

In the example above, the height of all the progress bars is decresed from 0.8rem (8px) to 0.5rem (5px) by overriding the --progress-bar-height variable in the global scope (:root).

A new component is also created (.battery) which is designed to show the available battery percentage of a system. This is done by overriding the progress bar variables in local scope, ie, .battery {...}. This is a great example to understand how new components and styles can be created by simply overriding the existing variables in a local scope. With so many variables available, there is usually no need to write traditional CSS.

Given below is another example showing how local scoping can be used to create a contextual card.

Please note that the .text-smoothing-auto class removes anti-aliasing from the text. You can learn more about anti-aliasing in the text utilities section (opens in new tab).

Colors #

Halfmoon comes with a bunch of colors. Each color has five different shades (including the base). These variables come in the following formats: --{name}-color, --{name}-color-light, --{name}-color-very-light, --{name}-color-dark, and --{name}-color-very-dark. The {name} is obviously the name of the color, for example, blue or red.

Each color also has two more variables for box shadows (using RGBA with varying opacity). These are mostly used for focus effects on elements. They come in the following format: --{name}-box-shadow-color and --{name}-box-shadow-color-darker. Moreover, each color also has a variable for a color that should be set as the color of text placed on the base shade of that color (--text-color-on-{name}-color-bg).

Colors in Halfmoon are divided into two categories:

System colors

Eight different system colors are available: blue, indigo, teal, green, yellow, orange, red and pink. Each color has eight different variables, for the shades, box shadows, and text color on base (as discussed above).

However, please note that system colors are not used in classes and components. They are instead extended by context colors which are then used in the components and utilities.

Context colors

Four different context colors are available: primary, success, secondary, and danger. Once again, each color has eight different variables, for the shades, box shadows, and text color on base (as discussed above). These colors are used in components and utilities. By default, each context color is set to a system color. The default values are as follows:

• primary context color set to blue system color.
• success context color set to green system color.
• secondary context color set to yellow system color.
• danger context color set to red system color.

You can override a context color by setting all of its variables to the corresponding variables of a system color (as shown in the very first example on this page). Another example is shown in the code below.

Variable inheritance #

Variable inheritance is when the value of a CSS variable is a reference to another one. So if the value of the reference variable is changed, all the variables extending it will also update automatically without needing to be manually set.

This is a very simple, but powerful concept that makes building custom themes a breeze, and Halfmoon has a lot of smart use of variable inheritance. For instance, the example below shows a card with a button in it. It has been customized using the same variables shown in the very first example on this page. Click on the button to open a modal.

As can be seen above, even though modal variables have not been overridden, the modal has been automatically customized to look like the card, because the modal variables inherit (or extend) the card variables. This is amazingly powerful because you can override only a small set of variables, but the result is a consistent theme, thanks to variable inheritance.

Native browser support #

Preprocessor variables have to be compiled before the browser can understand them, so there is an extra compilation step where the preprocessor turns them into native CSS. CSS variables, on the other hand, work directly on browsers that support them, so there is no extra compilation step using JavaScript. You write your CSS and the browser immediately understands it.

Read and set with JavaScript #

This point ties into the previous one, but it is important enough to be stated separately. Because CSS variables are natively understood by the browser, they can be read and set (or changed) using JavaScript in runtime. This is shown in the code below.

Imagine building a dashboard where the user is able to set their preferred colors, sidebar width, content padding, font size, mode (light or dark), and everything else in between. The settings are saved client side, and when the user loads your site, JavaScript is used to set the corresponding CSS variables according to the user's preferences.

This is the next level of user experience, because it goes beyond just creating a theme. It gives the users the ability to choose exactly how they prefer their design settings. This is only possible with a framework built entirely using CSS variables, and with Halfmoon, you can do this by writing a few lines of JavaScript.

Better use of CDNs #

In Halfmoon, a custom theme is a CSS file with overridden variables (as shown above). In most cases, this is going to be tiny in size, especially compared to the actual library. You include this file in your template, and pull in halfmoon-variables.css using a CDN.

That way, you are getting the speed and caching of a CDN for pulling in the Halfmoon library (which is a big file), and your custom theme can be served from your own server (or even within a <style> tag). This is only possible because there is no build/compile process, and would definitely not be possible with preprocessors.

Other benefits #

There are also other benefits that CSS variables have over preprocessors:

• Preprocessor variables do not cascade.
• Preprocessor variables cannot be redefined within media queries and understand on which selector to apply on.
• CSS variables are future proof. They will continue to be supported and improved upon, because they are part of the CSS language specification.

If you want to learn more about these benefits, please refer to this article .