How to use Theme Colors in SPFX Web Parts

While Waldek Mastykarz and I were working on a new project, we ask ourselves what it needs to create the web part corresponding to the current site theme colors.
After a small research, we found the solution for that.

Tokenize your CSS

It seems like you can use some variable when you are writing your style sheet. The color property, therefore, needs to be formatted in a certain way.
Let’s say you like to use the themes primary color as the background of your web part you need to define the color value in a specific way.

The token “[theme:themePrimary]” gets automatically replaced with the proper theme color. If the framework is unable to find the and replace “theme:themePrimary” the default value gets assigned.
The web part now in the local workbench looks like this:

Workbench Web Part with themed color fallbacks

In Office 365 I applied a dark theme to my site, and the web part looks completely different but according to the color defined in the theme.

Office 365 Workbench web part with theme applied from site

Also, I opened an issue on SPFx-dev-docs because currently the default values are required for local development.

Practical hints on tokens

These tokens to allows the reuse of the colors of the theme and makes your web part perfectly matching to the current theme. During development, it might cause some troubles because the chance is high to mistype theses text-based definitions. There is also no chance that your code editor is capable of auto-complete and recommend these text strings.
The good news is that SPFx uses SASS which allows defining those strings including default values as variables.

Now your code editor can recommend you one the defined color slots while typing the CSS statements.

Import theme slots into your project

Well, the previous example only used two theme slots. In this case, it is easy but is there a complete list of theme options with fallback available. Sadly not at the moment I created that list of SASS variables based on the names of Office UI Fabric and the defined color there.

View on GitHub

To embed these variables there are basically two ways to use this in your code.

The easy way – Single Web Part

To use these variables, you only need to copy them to your web part CSS, and then you are ready to rock. The correct values then will be replaced during the SASS compilation process. The variables will not end up in your web part code.

The other easy way – Multiple Web Parts

In case you have more than one web part in your project you redefine the variables all over again. Instead, you can save the theme in a file in your web parts root folder.
You can choose any file name you like. On thing, you should take care of that the name starts with an underscore. SASS will interpret this underscore prefixed file as a partial file, and the compiler will not compile a separate CSS file.
So you do not need to have an additional style import in your web part, but you need to import this SASS file into the SASS file of your web part.

You might need to adapt the path depending on where you stored your ‘theming.scss’ file. After this small import statement, all SASS variables are available in your web part style sheet.

Let’s see how this looks in local workbench now,

Local Workbench themed web part

alternatively, in Office 365 on a black themed site.

Office 365 Workbench on black themed site

Alternatively, in a beautiful orange themed site

Office 365 Workbench with a beautiful orange themed Web Part

Now you can make year web parts consistent with the theme of the site the web part is embedded too.

Bonus Content

If you have trouble find out the color available in the theme, there is an easy solution for that. The global variable __themeState__ contains all defined color and slots used by the theme.

Available Theme Slots shown in Web Inspector

This is the complete list:

View on Github

If you have any suggestions how to improve the SASS variable handling or noticed a bug please let me know.

Have fun creating themed SPFX web parts.


Also published on Medium.

  • Joel Rodrigues

    The yeoman generator should ask you if you want this and add the file when creating the project…
    Please do every developer a favour and submit this as a improvement suggestion on Github 🙂

  • Joel Rodrigues

    Hi Stefan, I’ve just tried this and I believe your import is wrong: should it not be
    @import ‘_theming’; ?

    • It depends where you store that file. In my case I stored it directly under ‘./src/webparts’ there for I have to navigate two levels up in the folder structure.
      Also as mentioned in the blog post the underscore is not required because of the SASS partial file name convention. These are files that won’t be compiled into a SASS but can be consumed by other SASS files if needed. Check out http://sass-lang.com/guide under partials and imports.