Use theme colors in your SharePoint Framework customizations

When building SharePoint Framework customizations, you should use theme colors so that your customizations look like a part of the site. This article explains how can you refer to the theme colors of the context site in your SharePoint Framework solution.

Note

Although this article uses a SharePoint Framework client-side web part as an example, the described techniques apply to all types of SharePoint Framework customizations.

Fixed colors vs. theme colors

When you scaffold a new SharePoint Framework client-side web part, it uses a fixed blue palette. When you add such a web part on a modern site by using a different color scheme, it stands out and doesn't look like a part of the site.

SharePoint Framework client-side web part using the blue color scheme on a modern team site using the red theme

When using fixed colors, you decide upfront which colors you want to use for which elements. This can lead to a situation like the one just illustrated, where a blue web part is displayed on a red team site, standing out unnecessarily. In most cases, you should strive to leverage the theme colors of the context site so that your solution doesn't stand out but looks like a part of the site.

Instead of using fixed colors, SharePoint Framework allows you to refer to the theme colors of the context site. As a result, if your web part is placed on a site that uses a red theme, it uses the red palette as well, and if it's placed on a site that uses the blue theme, it automatically adjusts itself to use the blue palette. All of this is done automatically without any changes to the web part code in between.

Use theme colors in the SharePoint Framework

When working with fixed colors, you specify them in CSS properties, for example:

.button {
    background-color: #0078d7;
}


To use a theme color instead, replace the fixed color with a theme token:

.button {
    background-color: "[theme: themePrimary, default: #0078d7]";
}


When your SharePoint Framework customization is loading on the page, the @microsoft/load-themed-styles package, which is a part of the SharePoint Framework, looks for theme tokens in CSS files and tries to replace them with the corresponding color from the current theme. If the value for the specified token is not available, SharePoint Framework uses the value specified by using the default parameter instead, which is why it's important that you always include it.

The following theme tokens are available for you to use:

Token Default value on a modern team site using the red palette Remarks
backgroundImageUri none
accent #ee0410
themeDark #b3030c Used for action icons in the command bar and as a hover color.
themeDarkAlt #b3030c
themeDarker #770208
themeLight #fd969b
themeLightAlt #fd969b
themeLighter #fecacd
themeLighterAlt #fecacd
themePrimary #ee0410st Primary theme color. Used for icons and default buttons.
themeSecondary #fc6169
themeTertiary #fd969b

Note

There are more tokens registered with the SharePoint Framework. While all of them have values specified on classic sites, only the subset mentioned earlier has values on modern SharePoint sites. For the complete list of available tokens, see the value of the window.__themeState__.theme property by using the console in your web browser's developer tools.

Use theme colors in your customizations

When you scaffold a new SharePoint Framework client-side web part, by default, it uses the fixed blue palette. The following steps describe the necessary adjustments to have the web part use theme colors instead.

Note

The following steps apply to a SharePoint Framework client-side web part named HelloWorld built by using React. For web parts built using different libraries and other types of customizations, you might need to adjust the modifications accordingly.

To use theme colors

  1. In the code editor, open the ./src/webparts/helloWorld/components/HelloWorld.tsx file, and from the div with class ms-Grid-row, remove the ms-bgColor-themeDark class.

    The 'ms-bgColor-themeDark' class selected in Visual Studio Code editor

  2. In the same folder, open the HelloWorld.module.scss file. Change the .row selector to:

    .row {
        padding: 20px;
        background-color: "[theme: themeDark, default: #005a9e]";
    }
    


    The .row selector extended with background color

  3. In the .button selector, change the background-color and border-color properties to:

    .button {
        /* ... */
        background-color: "[theme: themePrimary, default: #0078d7]";
        border-color: "[theme: themePrimary, default: #0078d7]";
        /* ... */
    }
    


    The .button selector updated with references to theme colors

  4. When you add the web part to a site, the colors used by the web part automatically adapt to the theme colors used by the current site.

    Side-by-side view of the same web part displayed in two sites using different colors. The web part follows the color scheme of each website

See also