SharePoint Framework - CSS Considerations

Overview

 

SharePoint Framework (SPFx) client-side web parts are lightweight and work on both classic and modern SharePoint sites. The look and feel is an integral part of a web part. CSS (Cascading Style Sheet) helps to apply the better look and feel to SharePoint web parts.

 

The Office UI Fabric helps in designing a seamless experience in Office 365. Please refer to my previous article here for more information. However, in certain scenarios, we also have to override a few default CSS classes offered by Office UI Fabric and SharePoint Framework

 

In this article, we will explore the common CSS considerations while developing SPFx web parts and how to override the default external reference classes from other components when needed. 

 

Manage CSS files in the SPFx solution

 

The SPFx solution consists of many components. Each component should be isolated and can be used individually whenever needed. Considering this, the CSS styles used by the component should be stored along with other assets used by that component.

 

Below is the recommended structure of SPFx solution based on React that uses multiple components.

 

Use of Sass

 

SharePoint Framework supports both SASS and CSS. SASS (Syntactically Awesome Style Sheets) is interpreted or compiled to CSS. SASS is a superset of CSS and it allows us to use variables, nested rules, mixins, inline imports, and much more, with fully CSS-compatible syntax.

 

More information about SASS can be found here (https://sass-lang.com/).

 

Use CSS classes over ID

 

Each element on a page can be accessed by ID or with CSS applied to it. Similarly, each element in SharePoint Framework web part can have an ID and CSS.

 

In real case scenarios, we may have multiple instances of the web part on a single page. Hence referring to the elements by ID inside markup might not be a good idea since an ID should be unique.

 

The below code uses ID to refer to an element and is not recommended to use.

export default class GettingStartedWebPart extends BaseClientSideWebPart<IGettingStartedWebPartProps> {

  public render(): void {
    this.domElement.innerHTML = `
      <div id="greetMessage">
        Welcome to SharePoint Framework
      </div>`;
  }
}

It is recommended to use the code like below, which refers to the elements by CSS class.

export default class GettingStartedWebPart extends BaseClientSideWebPart< IGettingStartedWebPartProps> {

  public render(): void {
    this.domElement.innerHTML = `
      <div class="${styles. greetMessage}">
        Welcome to SharePoint Framework
      </div>`;
  }
}

Use CSS Modules

 

SharePoint Framework web part is just one of the components along with other web parts or controls on the SharePoint page. CSS styles of one SPFx web part may conflict with CSS styles of another SPFx web part or other controls on the page.

 

SPFx resolves this conflict issue by CSS modules. The SPFx toolchain processes all the files with .module.scss extension and appends a unique hash value to each file.

 

For example, if we have the below files in the solution.

 

employee.module.scss

.employee {
     margin: 1em 0;

     .text {
          font-weight: bold;
          font-size: 1em;
     }
}

department.module.scss

.department {
     padding: 0.5em 1em;

     .text {
          font-weight: italic;
          font-size: 0.5em;
     }
}

After building the project, the above .module.scss file gets converted to the CSS files in the lib folder as below.

 

employee.module.css

.employee_f6071de4 {
     margin: 1em 0;
}

.employee_f6071de4 .text_f6071de4 {
          font-weight: bold;
          font-size: 1em;
}

department.module.css

.department_2f9c53f0 {
     padding: 0.5em 1em;
}

.department_2f9c53f0 .text_2f9c53f0 {
          font-weight: italic;
          font-size: 0.5em;
}

The CSS class generated is unique. Even though there is the same CSS class name being referred to in different web parts, the hash value generated makes them distinct.

 

Override external referenced CSS

 

We refer to various components in our SPFx web parts like Office 365 UI Fabric, or any third party UI components. These components come with their predefined CSS. We may need to override any of the CSS classes of an externally referenced component. In this case, we can use “global” keyword to override the CSS class in our .module.scss file as below.

// Make workbench canvas use full page width
:global(#workbenchPageContent) {
    max-width: initial;
}

// Override third party SuperTreeView CSS
:global(.super-treeview>div>.super-treeview-node>.super-treeview-node-content>input[type=checkbox])
{
  -webkit-appearance: radio; /* Chrome, Safari, Opera */
  -moz-appearance: radio;    /* Firefox */
}

Summary

 

SharePoint Framework web parts support SASS and CSS. Each component should have its own CSS references to maintain the isolation. Always refer to the elements by CSS class instead of ID. The external CSS styles can be overridden using "global" keyword.