CSS Custom Properties for Coloring the Visual Scheduling Widget

Posted by Juergen Theis on Jun 22, 2023 11:39:05 AM

In this blog post, you will learn an alternative approach to coloring the Visual Scheduling Widget - VSW for short - using CSS custom properties instead of calls to the widget’s API.

Why is styling by API calls provided at all?

When thinking about styling of HTML elements, the first thing that comes to mind is the use of cascading style sheets. Nevertheless, we decided from the very beginning of the development of VSW not to go this way for flexibility reasons.

VSW is a very fast changing component with a high dynamic functional growth. This implies that not only the code, but also the structure of the generated DOM is changing continuously. If we were to publish this structure and allow developers to style the widget by CSS, we would lose all the flexibility needed to improve and extend the widget without hindering the developer with breaking changes.

So far, each option or object property that controls a color of an element in VSW can be set a value of type string that represents a “CSS color value”. This means that you have, for instance, the following options to specify a color value:

  1. a predefined color name that CSS supports, such as "red", "green", or "blue"
  2. a hexdecimal notation, such as "#FF0000", "#00FF00", or "#0000FF"
  3. an RGB or RGBA notation, such as "rgb(255, 0, 0)", "rgb(0, 255, 0)", or "rgba(0, 0, 255, 0.5)"
  4. an HSL and HSLA notation, such as "hsl(0, 100%, 50%)", " hsl(120, 100%, 50%)", or " hsla(240, 100%, 50%, 0.5)"

The drawback of this proceeding is that the widget must navigate through the entire DOM to set the desired color to the corresponding elements. Only then can the browser determine the styling based on the CSS rules.

How to use CSS custom properties in VSW

However, since the current versions of all relevant web browsers supported by VSW provide custom CSS properties, a new alternative for styling opens up. VSW can now use this concept to color all of its parts that previously could only be colored by setting options or object properties. This way, you as an application developer get more flexibility in designing the VSW.

Instead of using one of the notations described above, you can also enter custom properties in your CSS definition and add references to these properties as “CSS color values”. Suppose you want to set the background color of the timescale to the color value "magenta", then you can define your own CSS property – e.g. --timescale-background – and set its value to "magenta":

#vswID {

   --timescale-background: magenta;


To apply this property, the VSW option timescaleBackgroundColor must be set as follows:

vswInstance.option("timescaleBackgroundColor", "val(--timescale-background) ");

If you intend to provide a color as fallback in case of the CSS property is missing, another value can be added. In the following example, we use black as fallback:

vswInstance.option("timescaleBackgroundColor", "val(--timescale-background, black)");


Use case "switching a color theme"

Now you may wonder what benefit this approach can have. One possible use case could be that you want to quickly switch your application between different color themes – e.g. between dark and light mode – by changing only style sheets.

In this case, you will create style sheets for each theme that differ in the settings for the CSS properties only. Switching the color theme means that the browser will process the colors by evaluating the corresponding styles. This is a task for which a browser is optimally prepared, and which it can perform quickly and efficiently. There is no need for the widget to navigate through the DOM and explicitly set the styles for each affected element.



In conclusion, VSW's use of CSS custom properties provides greater flexibility in styling by allowing developers to define and reference custom properties for element colors. This eliminates the need for the application to explicitly set colors for each object, making tasks like switching color themes more efficient. And besides, this approach leverages the optimized style processing capabilities of the browser.


Next step

Those who do not yet have the VSW SE in use are welcome to test it free of charge for 30 days. 

Schedule an introductory meeting with our Gantt chart experts   & get access to a free trial version   of our Visual Scheduling Widget for HTML5 Gantt charts


Topics: HTML5 Gantt Charts, Gantt Chart Controls