SharePoint Framework Theming and Office UI Fabric React
On 7 minutesI don’t think you need to be reminded that when you build SharePoint Framework customizations, you should use theme colours so that your customizations look like a part of the site.
If you use fixed colours, your web parts will not adjust to theme changes. For example:
.selector{
background-color: #0078d7;
}
will have #0078d7
colour regardless of the theme used by SharePoint. You should rather use
@import '~@microsoft/sp-office-ui-fabric-core/dist/sass/SPFabricCore.scss';
.selector{
background-color: "[theme: themePrimary, default: #0078d7]";
}
When your SharePoint Framework customisation is being loaded 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 colour 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.
Office UI Fabric React
When using Office UI Fabric React components, the same principle apply.
@import '~office-ui-fabric-react/dist/sass/_References.scss';
.selector {
background-color: $ms-color-themeDark; // use dark colour from SharePoint site theme
border-color: $ms-color-themePrimary; // use primary colour from SharePoint site theme
color: $ms-color-white; // use white colour from SharePoint site theme
}
Notice that we imported ~office-ui-fabric-react/dist/sass/_References.scss
instead. It is recommended that you uninstall the @microsoft/sp-office-ui-fabric-core package which is already installed in your solution by the Yeoman generator, if you decide to use Fabric components, in order to reduce your component bundle size.
npm uninstall @microsoft/sp-office-ui-fabric-core --save
Whenever you use any Fabric React component, they automatically adjust to the SharePoint site theme.
import { PrimaryButton} from 'office-ui-fabric-react/lib/PrimaryButton';
render() {
...
<div>
<PrimaryButton>click me</PrimaryButton>
</div>
...
}
Available theme tokens and their occurances
Token | Default | Color | Remarks |
---|---|---|---|
themeDark |
#7c1d21 |
Some button onclick and link color (e.g., “Return to classic SharePoint”). Header “Follow” star icon if the third header background color option is used. System pages: OK button border and hover. | |
themeDarkAlt |
#932227 |
Many icons (e.g., in the command bar), some borders, button/link hovers, spinner background, range element focus, checkbox background hover, web parts and lists, button hover, range element focus, add web part icon when the third section background color is selected. | |
themeDarker |
#5b1519 |
Hover color for some links. System pages: Visited link color. | |
themeLight |
#e3afb2 |
Range selector hover and focus background. Loading spinner background color in site contents view. | |
themeLighter |
#f0d3d4 |
Navigation edit menu background color, add web part panel hover background color, image background color in some web parts when the third section background color option is selected. System pages: Navigation hover background, cancel button hover background. | |
themeLighterAlt |
#fbf4f4 |
One of the section background options. Cogwheel menu hover background in site contents view. | |
themePrimary |
#a4262c |
Some button and checkbox backgrounds, links, texts, borders and icons, icon and link hovers. Also the footer background color, and one of the section background options. System pages: OK button background, link texts. | |
themeSecondary |
#ae383e |
The suite bar text in site contents view. Hover color for some links. Image background color in some web parts when the fourth section background color is selected. The second color in the palette icon in the “Change the look panel” (hence the token name) | |
themeTertiary |
#c86c70 |
Add web part icon when the fourth selection background color is selected. The third color in the palette icon in the “Change the look panel” (hence the token name) | |
neutralDark |
#212121 |
Some button, link and border hover text, some icons. System pages: page breadcrumb, header texts. | |
neutralLight |
#eaeaea |
Some web part borders, command bar action hover, command bar background when a list item is selected, list view category header background when an item is selected, button hover. System pages: Ribbon tab background, OK button border, selected navigation element background, disabled text box border. Divider web part. Image background color in some web parts when the second section background color option is selected. | |
neutralLighter |
#f4f4f4 |
Some menu backgrounds (e.g., the command bar), selected left navigation element, some button backgrounds, one option for a section background color. | |
neutralLighterAlt |
#f8f8f8 |
Left navigation hover background, list info panel text background, image background color in some webparts when the first section background color is selected, some icons and texts when editing web parts. System pages: Cancel button background, disabled text box background. | |
neutralPrimary |
#333333 |
Site header texts, texts in navigation menus, command bar, buttons and web parts, web part related icon backgrounds when the page is in edit mode, add web part panel icons and texts, web part settings panel texts. System pages: dropdown arrow color, some texts. | |
neutralPrimaryAlt |
#3c3c3c |
The suite bar background in site contents view. | |
neutralSecondary |
#666666 |
Some menu texts, empty library text, some icon hover backgrounds, some texts in web parts, command bar arrows, range selector. System pages: link color, some icons, and borders. | |
neutralTertiary |
#a6a6a6 |
Some button texts, some web part titles, some web part setting texts, some web part icons, border hover in some web parts, dashed section border in edit mode, web part settings panel control border. Most visible when editing web parts. System pages: text box, dropdown, and button border color. | |
neutralTertiaryAlt |
#c8c8c8 |
Some texts, e.g., in web part property pane, some icons in web parts, range selector background, some button onclick background, yes/no toggle control background, change section background color setting border. | |
neutralQuaternary |
#d0d0d0 |
Command bar action hover background when a list item is selected. System pages: Borders | |
black |
#000000 |
Web part settings panel dropdown text, carousel controls, site contents tab text hover, “Change the look” panel texts. | |
white |
#ffffff |
Primary body background, search input background, some button text, hub navigation text if the themePrimary header background is selected, one of the available section background colors. System pages: Body background | |
neutralQuaternaryAlt |
#dadada |
Info icon and selected ellipses background in lists, some web part element backgrounds when in edit mode, web part property pane dropdown item background, selected list item background. | |
accent * |
#ca5010 |
The fourth color in the palette in the “Change the look” panel. | |
whiteTranslucent40 * |
"rgba(255,255,255,.4)" |
Covers the rest of page when a modal dialog is opened. | |
blackTranslucent40 * |
"rgba(0,0,0,.4)" |
Covers the rest of page during certain modal dialog states, i.e.: when the web part search dialog is expanded | |
backgroundOverlay * |
(empty) | Site contents primary background, some borders, i.e.: between hub and site navigation | |
primaryBackground * |
#ffffff |
Some backgrounds when editing web part settings, some text field backgrounds |
Other useful links