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/css-recommendations.md
+82-39Lines changed: 82 additions & 39 deletions
Original file line number
Diff line number
Diff line change
@@ -1,25 +1,26 @@
1
1
---
2
2
title: Recommendations for working with CSS in SharePoint Framework solutions
3
-
ms.date: 11/18/2017
3
+
description: Use CSS to define how your SharePoint Framework customization should look and behave.
4
+
ms.date: 1/24/2018
4
5
ms.prod: sharepoint
5
6
---
6
7
7
8
8
9
# Recommendations for working with CSS in SharePoint Framework solutions
9
10
10
-
When building SharePoint Framework solutions, you can use CSS to define how your customization should look like and behave. This article describes how you can make the best use of the capabilities provided with the SharePoint Framework and build your CSS styles in a robust way.
11
+
When building SharePoint Framework solutions, you can use CSS to define how your customization should look and behave. This article describes how you can make the best use of the capabilities provided with the SharePoint Framework and build your CSS styles in a robust way.
11
12
12
13
## SharePoint Framework customizations are part of the page
13
14
14
-
When building SharePoint customizations using the add-in model, the solution is isolated from other elements on the page. Your code is executed either in an iframe, as an add-in part, or as an immersive application taking control of the whole page. In both cases, your code is not affected by other elements and styles defined on the page.
15
+
When building SharePoint customizations using the add-in model, the solution is isolated from other elements on the page. Your code can be executed in an iframe as an add-in part, or as an immersive application that takes control of the whole page. In both cases, your code is not affected by other elements and styles defined on the page.
15
16
16
-
SharePoint Framework solutions are a part of the page and integrate fully with the page's DOM. While this removes a number of restrictions that come with the add-in model, it exposes your solution to a risk. Because it's a part of the page, unless explicitly isolated, all CSS styles present on the page will apply to it, potentially resulting in an experience different from intended. To avoid such risks, you should define your CSS styles in such a way so that they won't affect anything else on the page other than your customization.
17
+
SharePoint Framework solutions are a part of the page and integrate fully with the page's DOM. While this removes a number of restrictions that come with the add-in model, it exposes your solution to risk. Because it's a part of the page, unless explicitly isolated, all CSS styles present on the page apply to it, potentially resulting in an experience different from what you intended. To avoid such risks, you should define your CSS styles in such a way so that they won't affect anything else on the page other than your customization.
17
18
18
19
## Organize CSS files in your solution
19
20
20
-
The UI of your solutions often consists of multiple building blocks. In many JavaScript libraries these building blocks are called components. A component can be simple and define only the presentation or it can be more complex and include state and other components. Splitting your solution into multiple components allows you to simplify the development process and makes them easier to test and reuse in your solution.
21
+
The UI of your solutions often consists of multiple building blocks. In many JavaScript libraries, these building blocks are called components. A component can be simple and define only the presentation, or it can be more complex and include state and other components. Splitting your solution into multiple components allows you to simplify the development process and makes it easier to test and reuse the components in your solution.
21
22
22
-
Because components have presentation, they often require CSS styles. Ideally, components should be isolated and be able to be used on their own. With that in mind, it makes perfect sense for you to store CSS styles for the particular component along with all other asset files next to the component. Following, is a sample structure of a React application with a number of components each with its own CSS file.
23
+
Because components have presentation, they often require CSS styles. Ideally, components should be isolated and be able to be used on their own. With that in mind, it makes perfect sense for you to store CSS styles for the particular component along with all other asset files next to the component. Following is a sample structure of a React application with a number of components, each with its own CSS file.
23
24
24
25
```text
25
26
todoWebPart\components
@@ -33,13 +34,17 @@ todoWebPart\components
33
34
34
35
## Use Sass
35
36
36
-
In the SharePoint Framework you can use both CSS and Sass. Sass is a superset of CSS and offers you a number of features such as using variables, nesting selectors or using mixins - all of which simplify working with and managing CSS styles over long term. For a complete set of features see the [Sass website](http://sass-lang.com). All valid CSS is also valid Sass which is very helpful if you haven't worked with Sass before and want to gradually learn its capabilities.
37
+
In SharePoint Framework, you can use both CSS and Sass. Sass is a superset of CSS and offers you a number of features such as variables, nesting selectors, or mixins, all of which simplify working with and managing CSS styles over the long term.
37
38
38
-
## Avoid using ID's in markup
39
+
For a complete set of features, see the [Sass website](http://sass-lang.com). All valid CSS is also valid Sass, which is very helpful if you haven't worked with Sass before and want to gradually learn its capabilities.
39
40
40
-
Using the SharePoint Framework you build customizations that end-users add to SharePoint. It's impossible to tell upfront if the particular customization will be used only once on a page or if there will be multiple instances of it. To avoid issues, you should always assume that there are multiple instances of your customization on the same page. With that in mind, you should avoid using any ID's in your markup. ID's are meant to be unique on a page and if a user added your web part to the page twice, it would violate this premise possibly leading to errors.
41
+
## Avoid using IDs in markup
41
42
42
-
**Bad practice:**
43
+
Using SharePoint Framework, you build customizations that end-users add to SharePoint. It's impossible to tell upfront if the particular customization is used only once on a page or if there are multiple instances of it.
44
+
45
+
To avoid issues, you should always assume that there are multiple instances of your customization on the same page. With that in mind, you should avoid using any IDs in your markup. IDs are meant to be unique on a page, and if a user adds your web part to the page twice, it violates this premise, possibly leading to errors.
46
+
47
+
#### Bad practice
43
48
44
49
```ts
45
50
// ...
@@ -57,7 +62,9 @@ export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorld
57
62
}
58
63
```
59
64
60
-
**Good practice:**
65
+
<br/>
66
+
67
+
#### Good practice
61
68
62
69
```ts
63
70
// ...
@@ -79,11 +86,11 @@ export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorld
79
86
80
87
SharePoint Framework solutions are a part of the page. To ensure that CSS styles for one component don't affect other elements on the page, you should define your CSS selectors in such a way that they apply only to the DOM of your solution. It's tedious and error-prone to do this manually, but SharePoint Framework can do this automatically for you.
81
88
82
-
To help you avoid stylings conflicts, SharePoint Framework uses [CSS modules](https://github.com/css-modules/css-modules). When building the project, the SharePoint Framework toolchain processes all files with the **.module.scss** extension. For each file, it reads all class selectors and appends a unique hash value to them. Once finished, it writes the updated selectors to intermediate CSS files that are included in the generated web part bundle.
89
+
To help you avoid styling conflicts, SharePoint Framework uses [CSS modules](https://github.com/css-modules/css-modules). When building the project, the SharePoint Framework toolchain processes all files with the **.module.scss** extension. For each file, it reads all class selectors and appends a unique hash value to them. After it's finished, it writes the updated selectors to intermediate CSS files that are included in the generated web part bundle.
83
90
84
-
Following the example above, assume you had the following two Sass files:
91
+
Following the previous example, assume that you had the following two Sass files:
85
92
86
-
**todoList.module.scss:**
93
+
#### todoList.module.scss
87
94
88
95
```scss
89
96
.todoList {
@@ -96,7 +103,9 @@ Following the example above, assume you had the following two Sass files:
96
103
}
97
104
```
98
105
99
-
**todoItem.module.scss:**
106
+
<br/>
107
+
108
+
#### todoItem.module.scss
100
109
101
110
```scss
102
111
.todoItem {
@@ -108,9 +117,11 @@ Following the example above, assume you had the following two Sass files:
108
117
}
109
118
```
110
119
120
+
<br/>
121
+
111
122
After building the project, in the **lib** folder you would see the following two CSS files generated (line breaks and indenting added for readability):
112
123
113
-
**todoList.module.css:**
124
+
#### todoList.module.css
114
125
115
126
```css
116
127
.todoList_3e9d35f0 {
@@ -123,7 +134,9 @@ After building the project, in the **lib** folder you would see the following tw
123
134
}
124
135
```
125
136
126
-
**todoItem.module.css:**
137
+
<br/>
138
+
139
+
#### todoItem.module.css
127
140
128
141
```css
129
142
.todoItem_f7081cc4 {
@@ -135,11 +148,13 @@ After building the project, in the **lib** folder you would see the following tw
135
148
}
136
149
```
137
150
151
+
<br/>
152
+
138
153
Even though there was a **.text** class defined in both Sass files, notice how in the generated CSS files it has two different hashes appended to it, becoming a unique class name specific to each component.
139
154
140
155
The CSS class names in CSS modules are generated dynamically, which makes it impossible for you to refer to them in your code directly. Instead, when processing CSS modules, the SharePoint Framework toolchain generates a JavaScript file with references to the generated class names.
141
156
142
-
**todoList.module.scss.js:**
157
+
#### todoList.module.scss.js
143
158
144
159
```js
145
160
"use strict";
@@ -156,7 +171,9 @@ exports.default = styles;
156
171
//# sourceMappingURL=todoList.module.scss.js.map
157
172
```
158
173
159
-
To use the generated class names in your code, you first import the styles of your component and then use the property pointing to the particular class:
174
+
<br/>
175
+
176
+
To use the generated class names in your code, you first import the styles of your component, and then use the property pointing to the particular class:
For the CSS modules to work correctly you have to meet the following conditions:
193
+
<br/>
194
+
195
+
For the CSS modules to work correctly, you have to meet the following conditions:
196
+
197
+
* Your Sass files must have the **.module.scss** extension. If you use the **.scss** extension without **.module**, you see a warning in the build process. The Sass file is transpiled to an intermediate CSS file, but the class names *will not be made unique*. In cases when you need to override third-party CSS styles, this might be intended.
177
198
178
-
*your Sass files must have the **.module.scss** extension. If you use the **.scss** extension without **.module**, you will see a warning in the build process. The Sass file will be transpiled to an intermediate CSS file but the class names **will not be made unique**. In cases, when you need to override 3rd party CSS styles, this might be intended
179
-
* your CSS class names must be valid JavaScript variable names, so for example they cannot contain hyphens: `todoList` is correct but `todo-list` isn't
180
-
* camelCase naming for classes is recommended, but it's not enforced
199
+
*Your CSS class names must be valid JavaScript variable names. For example, they cannot contain hyphens: `todoList` is correct, but `todo-list` isn't.
200
+
201
+
*We recommend using camelCase naming for classes, but it's not enforced.
181
202
182
203
## Wrap your CSS styles in a class named after the component
183
204
184
-
By combining CSS modules with Sass' support for nesting rule sets you can simplify your CSS styles and ensure that they won't affect other elements on the page.
205
+
By combining CSS modules with Sass support for nesting rule sets, you can simplify your CSS styles and ensure that they don't affect other elements on the page.
185
206
186
-
When building CSS styles for a component, wrap them in a class named after the component. Then, in the component, assign that class to the component's root element.
207
+
When building CSS styles for a component, wrap them in a class named after the component. In the component, assign that class to the component's root element.
187
208
188
-
**todoList.module.scss:**
209
+
#### todoList.module.scss
189
210
190
211
```scss
191
212
.todoList {
@@ -195,7 +216,9 @@ When building CSS styles for a component, wrap them in a class named after the c
After transpilation, the generated CSS file will look similar to:
237
+
<br/>
238
+
239
+
After transpilation, the generated CSS file looks similar to:
215
240
216
241
```css
217
242
.todoList_3e9d35f0a {
218
243
display: block;
219
244
}
220
245
```
221
246
222
-
Because the selector begins with the unique class name, specific to your component, the alternative presentation will apply only to hyperlinks inside your component.
247
+
Because the selector begins with the unique class name specific to your component, the alternative presentation applies only to hyperlinks inside your component.
223
248
224
249
## Handling of CSS vendor prefix
225
-
In SPFx no vendor prefixed style properties are required in the SASS or CSS files of a project. If some of the SPFx supported browsers require prefixes they were added after the SASS to CSS compilation automatically. This method is also known as auto-prefixing and is a fundamental part of the CSS build chain in SPFx.
226
250
227
-
In case a web part should use the new flex box model defined by `display: flex` declaration. Some older WebKit-based and Internet Explorer versions require a particular vendor prefix defined in the CSS.
251
+
In SharePoint Framework, no vendor prefixed style properties are required in the Sass or CSS files of a project. If some of the SharePoint Framework-supported browsers require prefixes, they were added after the Sass to CSS compilation automatically. This method is also known as auto-prefixing, and is a fundamental part of the CSS build chain in SharePoint Framework.
252
+
253
+
In case a web part should use the new flex box model defined by the `display: flex` declaration, some older WebKit-based and Internet Explorer versions require a particular vendor prefix defined in the CSS.
228
254
229
255
```css
230
256
.container{
231
257
display: flex;
232
258
}
233
259
```
234
260
235
-
In the SASS code of the SPFx artefact does not need to have vendor prefixes included. After the SASS-to-CSS compilation, those were added automatically resulting in the following CSS declaration.
261
+
<br/>
262
+
263
+
The Sass code of the SharePoint Framework artefact does not need to have vendor prefixes included. After the Sass-to-CSS compilation, those were added automatically, resulting in the following CSS declaration.
236
264
237
265
```css
238
266
.container_7e976ae1 {
@@ -242,10 +270,13 @@ In the SASS code of the SPFx artefact does not need to have vendor prefixes incl
242
270
}
243
271
```
244
272
245
-
Removing already applied prefixes does not only make the code cleaner of the artefact. It also makes it easier to read and future-ready. This process is also configured to support only SPFx supported browser and makes it more error safe.
246
-
In case a web part already has vendor prefixes included in the SASS files that are not needed anymore the same process removes those declarations automatically.
273
+
<br/>
274
+
275
+
Removing already applied prefixes does not only make the code of the artefact cleaner, it also makes it easier to read and future-ready. This process is also configured to support only SharePoint Framework-supported browsers and makes it more error-safe.
247
276
248
-
The following example makes use of the `border-radius` property. A property that does not require vendor prefixes on the supported systems.
277
+
In case a web part already has vendor prefixes included in the Sass files that are not needed anymore, the same process removes those declarations automatically.
278
+
279
+
The following example makes use of the `border-radius` property, which does not require vendor prefixes on the supported systems.
249
280
250
281
```css
251
282
.container {
@@ -258,20 +289,32 @@ The following example makes use of the `border-radius` property. A property that
258
289
}
259
290
```
260
291
261
-
The resulting CSS in the package will be converted to the following code.
292
+
<br/>
293
+
294
+
The resulting CSS in the package is converted to the following code.
262
295
263
296
```css
264
297
.container_9e54c0b0 {
265
298
border-radius: 7px
266
299
}
267
300
```
268
301
269
-
For more details on auto-prefixing look at the documentation in the '[autoprefix](https://github.com/postcss/autoprefixer)' GitHub repository. The databased throughout this process is available on [caniuse.com](https://caniuse.com).
302
+
For more information about auto-prefixing, see the [autoprefixer](https://github.com/postcss/autoprefixer) GitHub repository. The database for this process is available on [Can I use__?](https://caniuse.com).
270
303
271
304
## Integrate Office UI Fabric
272
305
273
-
By making your customizations look and behave like the standard functionality of SharePoint and Office 365 you will make it easier for the end-users to work with them. Office UI Fabric offers you a set of controls and styles for use in your customizations to seamlessly integrate with the existing user experience. For more information on using Office UI Fabric in the SharePoint Framework, read the [Office UI Fabric integration guide](./office-ui-fabric-integration.md).
306
+
By making your customizations look and behave like the standard functionality of SharePoint and Office 365, you make it easier for end-users to work with them. Office UI Fabric offers you a set of controls and styles to use in your customizations to seamlessly integrate with the existing user experience.
307
+
308
+
For more information about using Office UI Fabric in SharePoint Framework, see [Using Office UI Fabric Core and Fabric React in SharePoint Framework](./office-ui-fabric-integration.md).
274
309
275
310
## Use theme colors
276
311
277
-
SharePoint allows users to choose the theme color for their sites. In your SharePoint Framework customizations you should follow the theme selected by the users to make your customization look like an integral part of the site rather than unnecessarily stand out. Because the theme is set by users in their site, you cannot tell upfront which colors your customization should use, but SharePoint Framework can dynamically load the currently active color scheme automatically for you. For more information about this capability read the [guide on using theme colors](./use-theme-colors-in-your-customizations.md).
312
+
SharePoint allows users to choose the theme color for their sites. In your SharePoint Framework customizations, you should follow the theme selected by the users to make your customization look like an integral part of the site rather than unnecessarily stand out.
313
+
314
+
Because the theme is set by users on their site, you cannot tell upfront which colors your customization should use, but SharePoint Framework can dynamically load the currently active color scheme automatically for you.
315
+
316
+
For more information about this capability, see [Use theme colors in your SharePoint Framework customizations](./use-theme-colors-in-your-customizations.md).
0 commit comments