Are CSS modules the way forward?

Recommendations for working with CSS in SharePoint Framework solutions

  • 7 minutes to read

When building SharePoint Framework solutions, you can use CSS to define how your customization should look and behave. In this article 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.

SharePoint Framework customizations are part of the page

When building SharePoint customizations using the add-in model, the solution is isolated from other elements on the page. Your code can 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.

SharePoint Framework solutions are a part of the page and integrate fully with the page's DOM. This eliminates various restrictions of the add-in model, it does arise However, while this removes a number of restrictions that come with the add-in model, it exposes your solution to risk. Since it is part of the page, as long as you don't explicitly isolate the solution, all will be on CSS templates defined on the page are applied to them. 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.

Organize CSS files in your solution

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 .

Because components have presentation, they often require CSS styles. Ideally, components should be isolated and be able to be used on their own. To achieve this, it makes sense to save a component's CSS styles along with all of the component's other object files. 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. Below is a sample structure of a React application with a number of components, each with its own CSS file.

Using SassUse Sass

In SharePoint Framework, you can use both CSS and Sass. Ass is a CSS parent language and offers a number of features that make working with and managing CSS styles long term make it easier. These functions include variables, nesting selectors, and mixins. 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.

For a complete set of features, see the Sass website. Any valid CSS code is also valid Sass code. 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.

Avoid using IDs in markup

Using SharePoint Framework, you build customizations that end-users add to SharePoint. It is impossible to predict beforehand whether a single instance of a customization will be implemented on a page 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.

To avoid issues, you should always assume that there are multiple instances of your customization on the same page. Therefore, you shouldn't have IDs in your Use markup. With that in mind, you should avoid using any IDs in your markup. IDs must always be unique on a page; If a user adds two instances of your web part to a page, doing so violates this policy and can result in errors. 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.

Not recommended: bad practice


To recommend: good practice

Use CSS modules to avoid styling conflicts

SharePoint Framework solutions are part of the page. To ensure that CSS styles for one component do not affect other elements on the page, you should use your CSS selectors so that they only apply to the DOM of your solution. This is tedious and error-prone if done manually, but it can be done automatically in SharePoint Framework. 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.

The SharePoint Framework uses CSS modules. To help you avoid styling conflicts, SharePoint Framework uses CSS modules. When you create a project, the SharePoint Framework tool chain processes all files with the file extension .module.scssWhen 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. Then the updated selectors are written to intermediate CSS files that are generated in the After it's finished, it writes the updated selectors to intermediate CSS files that are included in the generated web part bundle.

Following the previous example, assume that you had the following two Sass files:

todoList.module.scsstodoList.module.scss


todoItem.module.scsstodoItem.module.scss


After creating the project you would be in the folder lib see the following two generated CSS files (line breaks and indents have been added for readability): After building the project, in the lib folder you would see the following two CSS files generated (line breaks and indenting added for readability):

todoList.module.csstodoList.module.css


todoItem.module.csstodoItem.module.css


Although a .textClass was defined in both Sass files, you will notice that two hashes have been appended in the generated CSS files, creating a unique class name that is specific to each component. 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.

The CSS class names in CSS modules are generated dynamically, so you cannot refer to them directly in your code. Instead, when processing CSS modules, the SharePoint Framework toolchain generates a JavaScript file with references to the generated class names. 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.

todoList.module.scss.jstodoList.module.scss.js


To use the generated class names in your code, you must first import the styles of your component. Then use the property that points to the class in question: 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:

  • Your Sass files must have a .module.scss Your Sass files must have the .module.scss extension. If you use the file extension .scss without .modules a warning message will appear during the build process .scss extension without .modules, you see a warning in the build process. The Sass file is transpiled into an intermediate CSS file, but the class names cannot be made unambiguously. The Sass file is transpiled to an intermediate CSS file, but the class names will not be made uniqueIn cases when you need to override third-party CSS styles, this might be intended.

  • Your CSS class names must be valid JavaScript variable names. For example, they cannot contain hyphens: is correct, but isn't .

  • We recommend the CamelCase notation for naming classes. We recommend using camelCase naming for classes, but it's not enforced.

Wrap your CSS styles in a class named after the component

By combining CSS modules with Sass support for nesting rule sets, you can simplify your CSS styles and make sure they don't affect other page elements can simplify your CSS styles and ensure that they don't affect other elements on the page.

When building CSS styles for a component, wrap them in a class named after the component. In the component itself, the class must dem In the component, assign that class to the component's root element.

todoList.module.scsstodoList.module.scss


TodoList.tsxTodoList.tsx


After transpilation, the generated CSS file looks similar to:

Because the selector begins with the unique class name specific to your component, the alternative presentation applies only to hyperlinks inside your component.

Handling of CSS vendor prefix

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 called This method is also known as auto-prefixing, and is a fundamental part of the CSS build chain in SharePoint Framework.

If your web part uses the new flex box model (defined by the declaration), some older WebKit-based browsers and Internet Explorer versions require a specific provider prefix in the CSS code defined by the declaration, some older WebKit-based and Internet Explorer versions require a particular vendor prefix defined in the CSS.


The Sass code of the SharePoint Framework artefact does not need to have vendor prefixes included. After compiling Sass to CSS, these are automatically added so that the CSS declaration like looks like: After the Sass-to-CSS compilation, those were added automatically, resulting in the following CSS declaration.


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 configured to only support browsers supported by the SharePoint Framework. This process is also configured to support only SharePoint Framework-supported browsers and makes it more error-safe.

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.

The following example makes use of the property, which does not require vendor prefixes on the supported systems.


The resulting CSS in the package is converted to the following code.

For more information about auto-prefixing, see the autoprefixer GitHub repository. The database for this process is on Can I use__? The database for this process is available on Can I use__ ?.

Integrate Office UI FabricIntegrate Office UI Fabric

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 for customization that seamlessly integrate with the existing user interface to use in your customizations to seamlessly integrate with the existing user experience.

For more information about using Office UI Fabric in SharePoint Framework, see Using Office UI Fabric Core and Fabric React in SharePoint Framework.

Use theme colors

SharePoint allows users to choose the theme color for their sites. In order for your SharePoint Framework customization to look like an integral part of the website and not stand out unnecessarily, it should be the one chosen by the user 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.

Since users decide the design of a website themselves, they don't know beforehand which colors your customization should use. 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.

For more information about this capability, see Use theme colors in your SharePoint Framework customizations.