Neat Optional Custom Property Values Trick

Optional Values in Multi-Value CSS Properties

When working with CSS properties that accept multiple values, like transform, you may want some values to be conditional. A common pattern is using a custom property inside the value list:

.el {
  transform: translate(100px) scale(1.5) skew(5deg);
}

A natural approach is to make the custom property itself optional:

.el {
  /*         |-- default ---| |-- optional --| */
  transform: translate(100px) var(--transform);
}

However, this doesn't work as expected. If --transform is undefined, the entire property declaration is invalid and gets dropped. The fix is subtle: define a fallback that is an empty value, i.e., a comma followed by nothing:

.el {
  transform: translate(100px) var(--transform, );
}

The difference is the fallback , in the var() function. This behavior is explicitly allowed by the CSS Variables specification:

In an exception to the usual comma elision rules, which require commas to be omitted when they're not separating values, a bare comma, with nothing following it, must be treated as valid in var(), indicating an empty fallback value.

This technique is loosely related to the CSS Custom Property Toggle Trick, which relies on custom properties holding an empty space as their value.

Working with Comma-Delimited Properties

The trick applies to any multi-value property, including text-shadow, background, and filter. However, properties like text-shadow demand special care because they strictly require comma separators between values.

If the custom property is only ever used in a context where another value is already present, you can place the comma inside the custom property itself, directly after the opening parenthesis:

--text-shadow: ,0 0 5px black;

This approach prevents using the variable as the sole value of a property. To maintain flexibility, you can introduce abstraction layers: have the outer custom property reference lower-level custom properties that hold the actual values.

A Note on Sass

There is a known issue with the Sass compiler: it strips out the empty fallback (the trailing comma), which violates the CSS specification. The bug has been reported upstream. Until it's fixed, a practical workaround is using a fallback that renders nothing, such as:

transform: translate(100px) var(--transform, scale(1));