You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/spfx/use-theme-colors-in-your-customizations.md
+65-40Lines changed: 65 additions & 40 deletions
Original file line number
Diff line number
Diff line change
@@ -42,45 +42,6 @@ To use a theme color instead, replace the fixed color with a theme token:
42
42
43
43
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.
44
44
45
-
The following theme tokens are available for you to use:
46
-
47
-
| Token | Default value on a modern team site using the red palette | Remarks |
|`themeDark`|`#b3030c`| 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. |
50
-
|`themeDarkAlt`|`#b3030c`| 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. |
51
-
|`themeDarker`|`#770208`| Hover color for some links. System pages: Visited link color. |
52
-
|`themeLight`|`#fd969b`| Range selector hover and focus background. Loading spinner background color in site contents view. |
53
-
|`themeLightAlt`|`#fd969b`||
54
-
|`themeLighter`|`#fecacd`| 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. |
55
-
|`themeLighterAlt`|`#fecacd`| One of the section background options. Cogwheel menu hover background in site contents view. |
56
-
|`themePrimary`|`#ee0410`| 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. |
57
-
|`themeSecondary`|`#fc6169`| The suite bar text color 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) |
58
-
|`themeTertiary`|`#fd969b`| 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) |
59
-
|`neutralDark`| `` | Some button, link and border hover text color, some icons. System pages: page breadcrumb, header texts. |
60
-
|`neutralLight`| `` | 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. |
61
-
|`neutralLighter`| `` | Some menu backgrounds (e.g., the command bar), selected left navigation element, some button backgrounds, ome option for a section background color. |
62
-
|`neutralLighterAlt`| `` | Left navigation hover background color, 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. |
63
-
|`neutralPrimary`| `` | Site header texts, texts in navigation menux, 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. |
64
-
|`neutralPrimaryAlt`| `` | The suite bar background color in site contents view. |
65
-
|`neutralSecondary`| `` | 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. |
66
-
|`neutralTertiary`| `` | Some button texts, some web part titles, some web part setting texts, some web part icons, border hover color in some web parts, dashed section border color in edit mode, web part settings panel control border color. Most visible when editing web parts. System pages: text box, dropdown, and button border color. |
67
-
|`neutralTertiaryAlt`| `` | Some texts, e.g., in web part property pane, some icons in web parts, range selector background, some button onclick background color, yes/no toggle control background, change section background color setting border color. |
68
-
|`neutralQuaternary`| `` | Command bar action hover background when a list item is selected. System pages: Borders |
69
-
|`neutralQuaternaryAlt`| `` | Info icon and selected ellipses background in lists, some web part element backgrounds when in edit mode, web part property pane dropdown item background color, selected list item background. |
70
-
|`backgroundImageUri`|`none`||
71
-
|`accent`|`#ee0410`| The fourth color in the palette in the “Change the look” panel. |
72
-
|`black`| `` | Web part settings panel dropdown text color, carousel controls, site contents tab text hover, “Change the look” panel texts. |
73
-
|`white`| `` | Primary body background color, some icon hover color, one of the available section background colors. System pages: Body background color |
74
-
|`whiteTranslucent40`| `` | Covers the rest of page when a modal dialog is opened. A solid color can be specified to get rid of transparency. |
75
-
|`backgroundOverlay`| `` | Header background, comment section background, some borders, site contents primary background color |
76
-
|`primaryBackground`| `` | Some backgrounds when editing web part settings, some text field backgrounds, cogwheel menu background in site contents view. |
77
-
|`primaryText`| `` | Edit section icons. Cogwheel menu texts in site contents view. |
78
-
79
-
80
-
81
-
> [!NOTE]
82
-
> 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.
83
-
84
45
## Use theme colors in your customizations
85
46
86
47
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.
@@ -122,8 +83,72 @@ When you scaffold a new SharePoint Framework client-side web part, by default, i
122
83
123
84
124
85
86
+
### Support section backgrounds
87
+
88
+
A customziation utilizing theme colors may still stand out if it doesn't respond to section background changes via theme variants support. See [Supporting Section Backgrounds](./webparts/guidance/supporting-section-backgrounds.md) for more information.
89
+
90
+
A web part without theme variants support uses a white background regardless of the selected section background color.
91
+
92
+
93
+
94
+
A web part configured to support theme variants can apply the section background to the web part background.
95
+
96
+
97
+
98
+
## Available theme tokens and their occurances
99
+
100
+
In the context of modern SharePoint sites, the values associated with theme tokens have numerous occurances within front-end, system page, and SharePoint web part UI. To best match your customizations to the general look and feel, consideration should be made to using appropriate theme tokens.
101
+
102
+
The following theme tokens are available for you to use:
103
+
104
+
_Note: default values below correspond to the defaults on a modern team site when using the **red palette**._
| `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. |
109
+
| `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. |
110
+
| `themeDarker` | `#5b1519` | Hover color for some links. System pages: Visited link color. |
111
+
| `themeLight` | `#e3afb2` | Range selector hover and focus background. Loading spinner background color in site contents view. |
112
+
| `themeLightAlt` | `#eff6fc` | |
113
+
| `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. |
114
+
| `themeLighterAlt` | `#fbf4f4` | One of the section background options. Cogwheel menu hover background in site contents view. |
115
+
| `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. |
116
+
| `themeSecondary` | `#ae383e` | The suite bar text color 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) |
117
+
| `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) |
118
+
| `neutralDark` | `#212121` | Some button, link and border hover text color, some icons. System pages: page breadcrumb, header texts. |
119
+
| `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. |
120
+
| `neutralLighter` | `#f4f4f4` | Some menu backgrounds (e.g., the command bar), selected left navigation element, some button backgrounds, ome option for asection background color. |
121
+
| `neutralLighterAlt` | `#f8f8f8` | Left navigation hover background color, 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. |
122
+
| `neutralPrimary` | `#333333` | Site header texts, texts in navigation menux, 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. |
123
+
| `neutralPrimaryAlt` | `#3c3c3c` | The suite bar background color in site contents view. |
124
+
| `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. |
125
+
| `neutralTertiary` | `#a6a6a6` | Some button texts, some web part titles, some web part setting texts, some web part icons, border hover color in some web parts, dashed section border color in edit mode, web part settings panel control border color. Most visible when editing web parts. System pages: text box, dropdown, and button border color. |
126
+
| `neutralTertiaryAlt` | `#c8c8c8` | Some texts, e.g., in web part property pane, some icons in web parts, range selector background, some button onclick background color, yes/no toggle control background, change section background color setting border color. |
127
+
| `neutralQuaternary` | `#d0d0d0` | Command bar action hover background when a list item is selected. System pages: Borders |
128
+
| `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 color, selected list item background. |
129
+
| `black` | `#000000` | Web part settings panel dropdown text color, carousel controls, site contents tab text hover, “Change the look” panel texts. |
130
+
| `white` | `#ffffff` | Primary body background, search input background, some buttontext, hub navigation text if the themePrimary header background is selected, one of the available section background colors. System pages: Body background color |
131
+
| `accent`* | `#ca5010` | The fourth color in the palette in the “Change the look” panel. |
132
+
| `whiteTranslucent40`* | `"rgba(255,255,255,.4)"` | Covers the rest of page when a modal dialog is opened. A transparent color is recommended. |
133
+
| `blackTranslucent40`* | `"rgba(0,0,0,.4)"` | Covers the rest of page during certain mobal dialog states, i.e.: when the web part search dialog is expanded |
134
+
| `backgroundOverlay`* | (empty) | Site contents primary background, some borders, i.e.: between hub and site navigation |
135
+
| `primaryBackground`* | `#ffffff` | Some backgrounds when editing web part settings, some text field backgrounds |
136
+
137
+
*Not included in [theme generator](https://aka.ms/themedesigner).
138
+
139
+
Occurance of theme tokens within SharePoint UI may differ depending upon selected background colors (i.e., theme token, `white` is used for header navigation links if a dark header background is selected, otherwise `neutralSecondary` is used). See [Designing for section backgrounds using semantic slots](../design/semantic_slots.md) for more information.
140
+
141
+
> [!NOTE]
142
+
> There are more tokens registered with the SharePoint Framework, although only the subset mentioned above are assignable in custom themes on modern SharePoint sites (the rest being generated automatically by the theming engine). 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.
143
+
144
+
### Customizing theme colors
145
+
146
+
In order to customize theme colors, a custom theme should be created and added to a SharePoint tenant for selection on a target site or hub. See [SharePoint site theming](https://docs.microsoft.com/en-us/sharepoint/dev/declarative-customization/site-theming/sharepoint-site-theming-overview) for more information.
147
+
125
148
## See also
126
149
127
150
- [SharePoint themes and colors](../design/themes-colors.md)
151
+
- [Designing for section backgrounds using semantic slots](../design/semantic_slots.md)
- [How to use Theme Colors in SPFX web parts](https://n8d.at/blog/how-to-use-theme-colors-in-spfx-web-parts/) by Stefan Bauer (Office Development MVP)
129
-
- [How to Create a Multicolored Theme for a Modern SharePoint Online Site](https://laurakokkarinen.com/how-to-create-a-multicolored-theme-for-a-modern-sharepoint-online-site/) by Laura Kokkarinen (SharePoint PnP Core MVP)
154
+
- [How to Create a Multicolored Theme for a Modern SharePoint Online Site](https://laurakokkarinen.com/how-to-create-a-multicolored-theme-for-a-modern-sharepoint-online-site/) by Laura Kokkarinen (SharePoint PnP Core MVP)
0 commit comments