CSS custom properties

In addition to components ZUi Web also provides a wide range of CSS custom properties (a.k.a. CSS variables) that can be used to customize visual appearance of the application. There are two main use-cases for using ZUi CSS custom properties:

1. You want to customize the visual appearance of ZUi Web components
2. You want to use ZUi styling primitives to create your own components. This is especially valuable when you want to create components that should look like "ZUi" but that are too special to be included in the ZUi Web component library.

To get more information about css custom properties, see Using CSS custom properties.

Customize the visual appearance of ZUi Web components

To customize all ZUi components globally, you can override css custom properties in a global style tag like this:

<style>
  * {
    --zui-gu: 10px;
  }
</style>

In this example, we are overriding the basic grid unit so that all ZUi Web components will be bigger. You can also override the styling of individual components:

<style>
  zui-button {
    /* official API, meant to be altered */              
    --zui-button-width: 150px;

    /* internal API, unsupported */
    /* ---zui-button-default-width: auto; */
  }
</style>

Here we are setting an explicit width to the zui-button. See the docs page of the zui-button.

Notice: While it's technically possible to override all css custom properties for all components, we recommend to only override css custom properties that are officially documented, either in the Storybook documentation of the specific component or in one of the sub-pages of Basic. All other css custom properties might be subject to change in future versions of ZUi Web.

To easily identify properties which are officially supported, watch out for the two leading slashes. All custom properties starting with three slashes are considered internal.

Use ZUi styling for your own components

You can use ZUi Web css custom properties of the design tokens in your own application even without ZUi components. This way you can adopt the visual style of ZUi. This is also meant as a way to create your own custom elements that wouldn't fit into the ZUi Web component library.

For example, to use a ZUi core token as background and a semantic token as color:

<style>
#my-content {
  background-color: var(--zui-core-color-GS-110);
  color: var(--zui-semantic-sys--fg--default--enabled);
}
</style>

<div id="my-content">
	...
</div>

Opacity with official ZUi colors

All ZUi colors can be used directly as custom properties. But additionally each official semantic color exists in a RGB and Alpha list format, which can be used to mix-in an alpha channel.

These list format colors are suffixed with -rgb or -alpha and can only be used by being wrapped with a rgb or rgba functional notation.
E.g. for the color --zui-semantic-sys--bg--1st-default--disabled exists --zui-semantic-sys--bg--1st-default--disabled-rgb with the value of 255 255 255 and --zui-semantic-sys--bg--1st-default--disabled-alpha with the value of 0.5. Withe the -rgb color you can add your own opacity values or also core token opacities.

#my-content {
  background-color: rgba(var(--zui-core-color-SC-G-110-rgb), var(--zui-core-opacity-60));
}