CSS custom properties (variables)

Many components make use of CSS variables to set their styling - commonly with colour and padding parameters, but the usage can vary.

tip

A quick way to identify what CSS variables are in use is to use the developer tools in your browser to inspect the element's styles.

Take a look at this example mark-up:

<rapid-listbox>
    <rapid-button></rapid-button>
    <rapid-option value="apple">Apple</rapid-option>
    <rapid-option value="banana">Banana</rapid-option>
    <rapid-option value="strawberry">Strawberry</rapid-option>
</rapid-listbox>

The colour of the text on all these components is determined by the CSS variable --neutral-foreground-rest. You can set that variable at the level you require to style it. For this component, you probably want to keep the text colour consistent - so you can set the variable at the level of the host component.

:host {
  --neutral-foreground-rest: hotpink;
}

Running this example in the browser changes the colour of both the listbox options and the button to hotpink. Nice.

If you want to only set only the colour of the listbox items, and not the button, the CSS variable should be scoped to the listbox. In this case, the button still uses the default value.

rapid-listbox {
  --neutral-foreground-rest: hotpink;
}

The browser should now be showing the listbox value's color as hotpink, but the button's value should still be white.

You can also set this in complex selectors. The following example uses child and nth-child selectors:

rapid-listbox rapid-option:nth-child(odd) {
  --neutral-foreground-rest: hotpink;
}

This example sets the odd-numbered options to hotpink. So for the example template, the "Apple" and "Banana" options will be hotpink and the "Banana" option will be white.

Scope

The CSS variable configuration takes effect at whichever scope level you define it. From there, it cascades down to all children components. That's why in the previous example setting, the colour at the component level changes everything - it cascades down into all the rapid-listbox, rapid-option and rapid-button components. CSS variables are the only way to cascade styles down through the Shadow DOM.

If instead of encapsulating the style change to a component you applied it at the top level, you'd see the effect across the entire application for all components that use the CSS variable (and which don't overwrite it later).

For example, if you added this to your top level styles:

* {
  --neutral-foreground-rest: hotpink;
}

You can see that adding the style changes the colour of many Genesis components in your application.

Scope​

Scope