4/28/2017

Using SharePoint Themes colors in SPFx Client Side Web Parts

Often you can have a task where your custom web part style (colors, backgrounds) should change to fit current selected SharePoint Theme (Site Settings -> Change the look).
I have good news for you - it's really simple to implement in SPFx Client Side Web Part

It turns out that SPFx has out of the box 'Themes loader' that is loaded to all Modern Pages by default. And this loader can replace SASS variables of specific format with values from current theme.
All existing theme properties can be found in window object:
window.__themeState__.theme
After you decided what properties of theme you need you can use them in your .scss files like that:
$yourVar: "[theme:primaryBackground, default: #fff]";

.someStyle {
background: $yourVar;
}
Here we're initializing a SASS variable (SASS guidance) with a specific value that can be parsed by themes loader:
  • theme:primaryBackground shows what variable from theme to use
  • default shows what value to use if the theme variable is not set (for example, default Office theme has very few variables that are set)
Then we're using our custom variable in css class.
And that's it.
You can get working web part example from GitHub and presentation slides from SharePoint PnP community call from Docs.com

UPDATE 05/20/2017
I've decided to list all the theme's properties here and start to collect information what property is responsible for what elements of the UI as I didn't find any documentation on that.

Name Elements on Modern Page
backgroundOverlay
  • overlay that is applied to page header (part with page title and large background image)
primaryBackground
  • Background color of the page,
  • dialog primary button font color,
  • Feedback button font color
primaryText
  • Primary font color
  • Feedback button background color
themeDarker
  • hovered Follow and Share links' color (at right corner of Nav Bar)
themeDark
  • Command bar icons' color,
  • dialog hovered primary button background color,
  • hovered Feedback button background color
themeDarkAlt
  • Always the same as themeDark
themePrimary
  • Site Logo Acronym background color,
  • Command bar top border (actually, this border is set as bottom border of 'Site Header' element that contains Site Logo and Site Title),
  • color of Edit link in Quick Nav,
  • color of Follow and Share icons (at right corner of Nav Bar),
  • Nav Bar hovered links' color,
  • dialog primary button background color
themeSecondary
themeTertiary
themeLight
themeLighter
themeLighterAlt
black
cmdbarSelected
cmdbarSelectedHover
neutralDark
neutralPrimary
neutralPrimaryAlt
neutralPrimaryTranslucent50
neutralSecondary
neutralSecondaryAlt
  • background color of hovered Delete and Edit web part buttons in edit mode
neutralTertiary
  • border of web part in edit mode,
  • background color of add web part (+) button in edit mode
neutralTertiaryAlt
neutralQuaternary
neutralQuaternaryAlt
neutralLight
  • Command bar hovered button background color
neutralLighter
  • Command bar background color
neutralLighterAlt
  • Hovered Quick Nav link background color
white
blackTranslucent40
  • Dialog overlay
whiteTranslucent40
  • background color of page title input in edit mode
yellow
yellowLight
orange
orangeLight
redDark
red
magentaDark
magenta
magentaLight
purpleDark
purple
purpleLight
blueDark
blueMid
blue
blueLight
tealDark
teal
tealLight
greenDark
green
greenLight
error
errorBackground
success
successBackground
alert
alertBackground
infoBackground
info
orangeLighter
themeLightAlt
themeAccent
themeTertiaryAlt
themeAccentTranslucent10
suiteBarBackground
suiteBarText
suiteBarDisabledText
topBarBackground
topBarText
topBarHoverText
dialogBorder
backgroundImageUri
  • URL of background image for the page content

Please, feel free to add information about the properties in the comments. I will update the table with this info.
Have fun!


7 comments:

  1. Very useful - thank you.

    ReplyDelete
  2. Many thanks, very useful and time saving article :)

    ReplyDelete
  3. Hi Thanks Alex, great article. I have a code which generates dynamic HTML and style tags. How can I refer these SASS variables in it. I am using Typescript for creating custom web parts.

    ReplyDelete
    Replies
    1. You can reference it as styles. in your code.
      You can find example here: https://github.com/SharePoint/sp-dev-fx-webparts/tree/master/samples/react-side-panel/src/webparts/sidePanel/components/Panel
      There is a $duration variable in .scss and it is used in .tsx file.

      Hope, that explanation helps.

      Delete
    2. styles.name_of_variable

      Delete