0 comment

CSS Variables support for SPFx projects through spfx-uifabric-themes

It has been a while since I release the last version of my spfx-uifabric-themes npm package to make it easier to handle theming in SPFx projects.

New Release spfx-uifabric-themes

New Release spfx-uifabric-themes

I’m proud to present now a new version that supports theming through CSS variables instead of SASS variables. If you hear this the first time, let me give you a short introduction on that.

What are CSS Variables

Technically spoken CSS variables are an extension to the CSS3 standard and are defined in the CSS Custom Properties for Cascading Variables Module Level 1.

Instead of reading the full specification here is a short introduction.

:root{ // <- root of document
  --primaryText: #333333;  // definition of variable always start with '--'

All variable needs to be specified at the root level this is in most cases the same as writing HTML, but roothas a higher specificity. So the CSS code is more important than declarations specified on HTML.

A variable named --primaryTextis now specified and can be used on various places in your CSS file but need to be requested specially. Let’s define a custom paragraph for example that uses the primaryTextvariable as the background colour.

  background-color: var(--primaryText);

A variable can only be requested via the keyword var. The browser detects this request for the variable and replaces it with the actual colour.

Precisely the same way like in SASS but this will be done during the page load or when the CSS variable will be loaded not during compilation of the project.

What makes CSS variables better and different

SPFx compiles strings into the CSS files formatted like "[theme:themeDark, default: #005a9e]". A JavaScript pick up these values and replace it with the actual colour code and generates a new CSS that will be registered on the page. This is all JavaScript driven and can cause exceptions and slow performance.

Another thing to maintain is the right loading order, so some code has to wait until all CSS have been loaded to replace the values that might get slower when a lot of components are registered on a page.

CSS, on the other hand, doesn’t have any load order dependencies. If the variables are in the CSS defined but not defined on the root level. First no exception will be caused, and second, once the variable is available on the root level, the correct values will be applied to the component. This way it is absolute fail-safe and better performant than the actually theming implementation.

How it works in the spfx-uifabric-theme

All variables used for theming are defined in the global __themestate__object in the property theme.

ThemeState object on modern pages

So I fetch all properties and register the CSS variables on the page. (Yeah yeah I know DOM manipulation but only CSS). Since there is no native implementation in the modern experience yet, this is the only possible workaround.

In case another web part needs to register the CSS variable again the piece in SPFx-uifabric-themeI built in checks if those already have been registered. That safes render and execution time.

I also prefix the variable names with ouiffor office ui fabric. Instead of using the themed slot as AccentTextthe variable is named.--ouif-AccentText

CSS variables registered on page

Like before shown you can use the variable again in a custom paragraph like this.

  background-color: var(--ouif-AccentText);

Finally one significant benefit of using this theme based CSS variable is you have better control in your CSS. The currently implemented theming variables are all colour based and supports only 66 defined colours used in Office UI Fabric.

It doesn’t give you any indication of where the colour is used. The CSS variables generated out of the theming object supports currently 192 slots. The 66 Office UI fabric colour and things like ‘ButtonBackground’, ‘ButtonText’, and so on and so forth.

Overall better control to theme your web parts and eventually better performant. One thing is for sure. By using CSS variables, you take a sneak peek in the future of modern development that already has great support on the latest browser.

Screenshot generated only using CSS Variables in code

CSS variables themed web part – Option 1

CSS variables themed Option 2