Customizing JavaScript Styles with Sass

Introduction to Sass

Sass (Syntactically Awesome Style Sheets) is a CSS preprocessor -- a scripting language that extends CSS by allowing developers to write code in one language and then arranges it into CSS. CSS preprocessing simplifies the coding process by allowing you to add different features into your CSS (variables, nested rules, and mixins). Sass improves CSS the same way TypeScript improves plain JavaScript. It provides modularization, variables, structure, compiles time syntax checking, and functions.

We recently switched to Sass to make it easier to create and maintain Wijmo CSS files. Over the last few years, Sass has become the most popular CSS preprocessor, being supported by all popular frameworks.

Several frameworks that support Sass:

Just like TypeScript, Sass is optional. Yes, you can use the CSS files we build with Sass. However, if you want to customize the Wijmo styles to create your own themes, or create custom CSS files that include only the Wijmo modules you use, then we suggest using Sass.

Using Sass tools

If you choose to use Sass, you will need a Sass tool. Our favorites are:

We chose Sass over other CSS processors because of its popularity and functionality. Using Sass will make it easier to integrate Wijmo styling with the tools you are already using.

Several additional reasons to use Sass:
  • Modularity. Just like with any language, writing CSS without a well-defined architecture and/or organizational pattern quickly becomes an unmaintainable mess. We use one SCSS file per Wijmo module.
  • Variables. Variables are essential to allow the creation of themes. It’s easier and safer to change the value of the “$wj-sel-bkg” variable than to replace “#005c8f” with another value in several rules.
  • Structure. Sass supports rule nesting, which makes it easier to write rules in a concise and consistent way. This also reduces the temptation to pollute the CSS namespace with too many to-level selectors that act as “global variables”.
  • Compile time error-checking. If you misspell the name of a CSS property or value, Sass will tell you about it at compile-time. This can save a lot of time and frustration.

Wijmo JavaScript styles and Sass

We use the following folder structure for Wijmo’s Sass files:

wijmo.scss                    // main scss file  
misc  
    _constants.scss           // color names  
    _glyphs.scss              // Wijmo glyphs  
    _mixins.scss              // utility functions  
    _variables.scss           // theme variables  
  core                          // modules in Wijmo core  
    _chart.scss  
    _chart_hierarchical.scss  
    _chart_interaction.scss  
    _core.scss  
    _gauge.scss  
    _grid.scss  
    _grid_filter.scss  
    _grid_grouppanel.scss  
    _input.scss  
    _nav.scss  
  enterprise                    // modules in Wijmo enterprise  
    _chart_finance.scss  
    _multirow.scss  
    _olap.scss  
    _sheet.scss  
    _viewer.scss  
  themes                        // bundled themes  
    wijmo.theme.cerulean.scss  
    wijmo.theme.cleandark.scss  
    wijmo.theme.cleanlight.scss  
    etc… 

Following Sass conventions, files with names that start with an underscore are included by other files and do not generate stand-alone CSS files.

The wijmo.scss file is used to generate our main CSS file, wijmo.css. It contains the following:

// wijmo.scss  

// misc  
@import "misc/mixins"; // functions  
@import "misc/constants"; // named colors  
@import "misc/variables"; // theme variables  
@import "misc/glyphs"; // wijmo glyphs  

// core modules  
@import "core/core";  
@import "core/input";  
@import "core/grid";  
@import "core/grid_grouppanel";  
@import "core/grid_filter";  
@import "core/chart";  
@import "core/chart_interaction";  
@import "core/chart_hierarchical";  
@import "core/gauge";  
@import "core/nav";  

// enterprise modules  
@import "enterprise/sheet";  
@import "enterprise/multirow";  
@import "enterprise/olap";  
@import "enterprise/viewer";  
@import "enterprise/chart_finance";  

If you run this through the Web Compiler or any other Sass tool, you will get the regular wijmo.css and wijmo.min.css output files which are about 64 and 51k in size.

Building smaller CSS files with custom CSS

If you don’t use any of the Wijmo enterprise modules and would like to reduce the size of your CSS files, you could create a wijmo-core.scss file that looks like the wijmo.scss above. You'll need to omit the the last five lines (the ones that include the Wijmo enterprise modules).

This will create a wijmo-core.css file and a wijmo-core.min.css file that are about half the size of the original ones: just 31 and 25k.

We have done this for you already! The wijmo-core.css file is included in our distribution. But you can use this approach to generate optimized CSS files that include only the modules your application needs.

Building custom CSS themes

In addition to the standard wijmo.css file, Wijmo includes many custom themes. Most themes are created by overriding the value of a few variables. For example, the cerulean theme is created from the wijmo.theme.cerulean.scss file:

// cerulean theme  
$wj-bkg: #fcfcfc;  
$wj-txt: #082d43;  
$wj-bdr: none;  
$wj-hdr-bkg: #033c73;  
$wj-hdr-txt: #fff;  
$wj-sel-bkg: #2a9fd6;  
$wj-msel-bkg: #77afc9;  
$wj-cell-grp-bkg: #777777;  
//… etc …  

@import "../wijmo.scss";  

The theme file sets some Wijmo variables before including the Wijmo.scss file. That’s all there is to it. The output is a wijmo.theme.cerulean.css file that can be used instead of the standard wijmo.css.

This is an important change from previous versions of Wijmo, where the theme files extended (and required) the standard wijmo.css rather than replacing it. The new approach means one less file to include and load, which translates into faster-loading pages.

Building dynamic themes with custom CSS

CSS variables are already available on modern browsers (Edge, Chrome, Firefox, Safari). They allow you to define variables that are applied to CSS rules at runtime. The idea is the same as variables in Sass and LESS, except CSS variables are dynamic.

You can find out more about CSS variables in the CSS Variables: Why Should You Care?

You can use CSS variables in Wijmo by setting the Wijmo Sass variables to variable expressions. For example, consider this wijmo.themes.vars.scss file:

// wijmo vars theme (using CSS variables)  
body {  
    --mdl-primary: red;  
    --mdl-primary-light: pink;  
    --mdl-accent: green;  
}  

$mdl-primary: var(--mdl-primary);  
$mdl-primary-light: var(--mdl-primary-light);  
$mdl-accent: var(--mdl-accent);  

@import "wijmo.theme.material.scss";  

The file sets a couple of Wijmo SCSS variables to CSS variable expressions (var(--*)). Once this is done, the Sass propagates the assignment to all relevant CSS rules in the wijmo.theme.vars.css file.

If you change the value of the CSS variables at runtime, the change will be applied, and the appearance of the page will change instantly. No need to recompile or re-load any CSS.

For example, you could change the page colors using a couple of Wijmo InputColor controls:

var style = document.body.style,  
            computedStyle = getComputedStyle(document.body);  

// change primary color  
new wijmo.input.InputColor('#clrPrimary', { 
    showAlphaChannel: false, 
    value: computedStyle.getPropertyValue('--mdl-primary').trim(), 
    valueChanged: function (s, e) { 
       style.setProperty('--mdl-primary', s.value); 
       style.setProperty('--mdl-primary-light', lighten(s.value, .2)); 
    } 
}); 

// change accent color  
new wijmo.input.InputColor('#clrAccent', { 
    showAlphaChannel: false, 
    value: computedStyle.getPropertyValue('--mdl-accent').trim(), 
    valueChanged: function (s, e) { 
        style.setProperty('--mdl-accent', s.value); 
    } 
});  

// change accent color  
new wijmo.input.InputColor('#clrAccent', {  
    showAlphaChannel: false,  
    value: computedStyle.getPropertyValue('--mdl-accent').trim(),  
    valueChanged: function (s, e) {  
        style.setProperty('--mdl-accent', s.value);  
    }  
});

Ultimately, just like TypeScript, Sass is optional. You can use the CSS files we build with Sass. However, if you want to customize the Wijmo styles to create your own themes, or to create custom CSS files that include only the Wijmo modules you use, then we suggest using Sass!

For more articles like this, demos, videos and tutorials, check out our blog page. Do you have a demo request? Leave us a comment below!

Try Wijmo's controls with Sass

Download the latest version of Wijmo

Download Now!