Adding support for theme variants in SPFx web parts

Introduction

Since SPFx 1.8, we have been able to make web parts aware of what section they reside in on a modern page.

Each SharePoint site theme has four variants: the main variant, a neutral variant, a soft variant, and a strong variant.

You can configure each page section’s background color with one of the four theme’s variants.

When you place a web part on a section with a different background color, the web part has the ability to adapt to that section’s background color.

Microsoft has a great article explaining how to add section support to your web parts, but it does not go into great detail explaining the theme variants.

Theme variants define a lot of different colors, like the background color, body color, button colors, etc.

Every time I write a web part that is “theme-variant-aware,” I find myself looking up which theme colors I should use for each element in my web part.

If you dig enough in the SharePoint code (under sp-component-base) you’ll find helpful comments describing how to use each color of a theme variant.

Hoping this will help someone, I extracted the description of each color in theme variants from the comments and created this post.

Keep in mind that this information may change between versions of SPFx. I’ll do my best to keep it up-to-date between versions.

Adding support for theme variants

Before we explore the various colors that are available at your disposal, let’s discuss how to make your web part aware when a section theme variant changes.

When you create a new web part using the Yeoman generator, your web part does not adapt to theme variants. If you change the background color of the section where you web part resides, it mostly stays the same color, like the sample below:

To make it support theme variants, you need to follow these steps (this code is extracted from Microsoft’s article:

1. In your web part’s .manifest.json, add the following (I usually add it above the preconfiguredEntries):

   “supportsThemeVariants”: true,

2. At the top of your web part’s code (YourWebPartNameWebPart.ts, add the following imports:

   import {
     ThemeProvider,
     ThemeChangedEventArgs,
     IReadonlyTheme,
     ISemanticColors
   } from '@microsoft/sp-component-base';
   

3. In your web part class (just below export default class YourWebPartNameWebPart, add these two variables:

   private _themeProvider: ThemeProvider;
   private_themeVariant: IReadonlyTheme | undefined;
   

The _themeProvider variable will store the web part’s instance of the theme provider, which notifies the web part of the currently selected theme. The _themeVariant variable will store the currently selected theme variant.

4. Add an event handler in your web part to react to changing theme variants:

   private _handleThemeChangedEvent(args: ThemeChangedEventArgs): void {
     this._themeVariant = args.theme;
     this.render();
   }
   

5. In your web part code, add an onInit method to initialize the theme provider, get the initial theme variant, and associate the event handler:

   protected onInit(): Promise<void> {
     // Consume the new ThemeProvider service
     this._themeProvider = this.context.serviceScope.consume(ThemeProvider.serviceKey);
   
     // If it exists, get the theme variant
     this._themeVariant = this._themeProvider.tryGetTheme();
   
     // Register a handler to be notified if the theme variant changes
     this._themeProvider.themeChangedEvent.add(this, this._handleThemeChangedEvent);
   
     return super.onInit();
   }
   

6. In your web part’s render method, you’ll need to add code to pass the theme variant to your component:

   public render(): void {
     const element: React.ReactElement<IYourWebPartNameProps > = React.createElement(
       YourWebPartName,
       {
         themeVariant: this._themeVariant,
         // whatever other props you want to pass
       }
     );
   
     ReactDom.render(element, this.domElement);
   }
   

7. In your web part’s component’s props (IYourWebPartNameProps), add a prop for the theme variant:

   import { IReadonlyTheme } from '@microsoft/sp-component-base';
   
   export interface IYourWebPartNameProps {
     themeVariant: IReadonlyTheme | undefined;
   }
   

8. Finally, in your web part’s component’s tsx file, you can use the themeVariant prop to retrieve variant colors:

   public render(): React.ReactElement<IYouWebPartNameProps> {
   
     const { semanticColors }: IReadonlyTheme = this.props.themeVariant;
   
     return (
       <div style={{backgroundColor: semanticColors.bodyBackground, color: semanticColors.bodyText}}>
         <span className={ styles.title }>Welcome to SharePoint!</span>
         <p className={ styles.subTitle }>This web part is theme variant aware.</p>
       </div>
     );
   }
   

9. Once your rebuild your web part (gulp build) and add your web part to a page (remember: if you changed the manifest since you added the web part to a page, you need to re-add the web part), your web part will now be aware of section background colors:

You’ll notice that we use the bodyBackground and bodyText colors from the themeVariant. But theme variants define a lot more colors.

Theme variant colors

In a theme variant, you can find the palette colors (e.g.: themeDark, themePrimary, themeSecondary, etc.) and the semantic colors.

Your first instinct might be to try to use the palette colors, but that would require you to know exactly which color is applied to what element. For example, do you know which palette color is used for a button’s background color when a user mouses over it?

Me neither.

The semantic colors, however, describe how you would use each palette color semantically. For example, it tells you that the background color of a hover button should be buttonBackgroundHovered.

Here is the full list of semantic colors available within a theme variant. The list is extracted from Microsoft’s code.

Base colors

Text colors

Conclusion

Like chameleons, SPFx web parts can change colors to adapt to changing environments and blend in.

With a few lines of code and some knowledge of which semantic colors you can use, you can built awesome web parts that will look good no matter what theme (or theme variant) your site uses.

I hope this helps?

Photo Credits

Photo by Pierre Bamin on Unsplash