Using Custom Color for Section Backgrounds and Page Headers

Have you ever wondered where the background colors in SharePoint modern pages comes from? You know, the ones for section background colors and site headers? Have you ever wondered how to change them to your own custom colors?

I had a client that wanted to be able to set the background for the site headers to a specific color. Unfortunately, the color they wanted wasn’t one of the four colors available through the SharePoint UI.

It turns out not unexpectedly that these colors are controlled by the theme being used on the site. To create a set of custom colors you need to create a custom theme. You can do that using the UI Fabric Theme Designer. Once you have a custom theme created you deploy it to your tenant. The Theme Designer provides you with JSON or PowerShell for you to deploy the theme to your site. The PowerShell or JSON has tokens in it for the different colors and hex values assigned to each. Here is an example of the tokens provided by the Theme Designer.

"themePrimary" = "#0078d4";
"themeLighterAlt" = "#f3f9fd";
"themeLighter" = "#d0e7f8";
"themeLight" = "#a9d3f2";

The color used for the four background colors across SharePoint are from left to right:

  • white
  • neutralLighter
  • themeLighterAl
  • themePrimary

Depending on the colors you set these values to they will update the background colors available to you in the SharePoint UI.

The Theme Designer sets most of the colors to provide a sufficient amount of contrast in the color when using a light background and darker text or vice versa so I would not recommend changing these willy nilly but you do have the ability to tweak colors if they don’t exactly match your brand’s color palette. Here is some PowerShell to deploy the theme to your tenant.

#SharePoint admin site url
$adminSiteUrl = ""
$themeName = "My Custom Theme"
#ask user for credentials. User needs SharePoint Admin rights
$credentials = Get-Credential

#connect to SPO
Connect-SPOService $adminSiteUrl -Credential $credentials

#Replace the variable value with the generated code
$theme = @{
     "themePrimary" = "#0078d4"; #Fourth Background Color
     "themeLighterAlt" = "#f3f9fd"; #Third Background Color
     "themeLighter" = "#d0e7f8";
     "themeLight" = "#a9d3f2";
     "themeTertiary" = "#5ca9e5";
     "themeSecondary" = "#1a86d9";
     "themeDarkAlt" = "#006cbe";
     "themeDark" = "#005ba1";
     "themeDarker" = "#004377";
     "neutralLighterAlt" = "#f8f8f8";
     "neutralLighter" = "#f4f4f4"; #Second Background Color
     "neutralLight" = "#eaeaea";
     "neutralQuaternaryAlt" = "#dadada";
     "neutralQuaternary" = "#d0d0d0";
     "neutralTertiaryAlt" = "#c8c8c8";
     "neutralTertiary" = "#bab8b7";
     "neutralSecondary" = "#a3a2a0";
     "neutralPrimaryAlt" = "#8d8b8a";
     "neutralPrimary" = "#323130";
     "neutralDark" = "#605e5d";
     "black" = "#494847";
     "white" = "#ffffff"; #First Background Color

#I ran into a few issues with theme updating using the -overwrite
#command so removing it and re-adding it

Remove-SPOTheme -name $themeName
Add-SPOTheme -Name $themeName -Palette $theme -IsInverted:$false 

After you deploy the theme it will be available across all SharePoint Online sites for use. You will need to apply the theme to your specific site in order for it to use these colors either manually through the UI or through PowerShell.

One note of caution, the family of tokens are designed to work as a unit so changing one value may have unintended consequences. For example changing themeLighterAlt to a dark color instead of a light color will result in dark text on a dark background which is bad for readability and accessibility.

5 Comments Add yours

  1. Darren says:

    Hi Derek, thanks so much for the great post! I’ve really been struggling with trying to implement ThemeLighterAlt as a dark background color but with a light text color. Is it possible to target specific text colors that correspond to the 4 main background colors you’ve specified? I hope this makes sense.

    1. Hi Darren,
      You can definitely start messing around with the different color slots in the theme that gets output from the theme generator. The problem with this, and what I think you are running into is that SharePoint uses these different variables in many different places so changing the text in one of the variables could give you an undesired color combination in other places. That is sort of the reason that the theme generator only gives you three options to customize and generates the other values. It does this to ensure contrast and readability across colors. So, while it is technically possible for you to start editing all the color values do so with extreme caution. You don’t know how SharePoint uses all those values currently or might in the future.

      Laura Kokkarinen did a great post a while back outlining some of the different theme options and how they are used.

      I hope this helps.
      – Derek

  2. Martin says:

    Thank you a lot, Derek! I was struggling to understand and find which colors within designer match section background colors. This really helped me!

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.