The new SharePoint Framework has a smart way to avoid conflicting CSS definitions. Therefore all style sheet classes will be post-fixed with a unique random string and converted to a JSON object. In your web part code, you can use the same class name as you used in your style sheets and the variable will be automatically replaced with the random class name string. So far the good parts of the SharePoint Framework.
In practice, this has some limitations and challenges.
CSS naming conventions
From a professional web development perspective, you don’t class names as you like. A significant benefit is when you use clear defined guidelines how you name your elements in the style sheets. The most common naming conventions are:
- BEM – Block-Element-Modifier
- OOCSS – Object Oriented CSS
- SMACSS – Scaleable Modular Architecture for CSS
All those naming conventions have one thing in common. Those naming conventions make use of hyphens in class names. Office UI Fabric makes use of the SuitCSS naming convention which also defines hyphens for their class names.
Those naming conventions are widely used in web development but cause some challenges with the SharePoint Framework.
After the SharePoint Framework compiles your SASS style definition into CSS files, all class names will be post-fixed with and additional random string. The idea behind attaching a random string is that you get a set of unique class definitions scoped for your project. It makes sure that each class definition is only used once on a page and makes your web part safe of breaking and interfering with other web parts.
While the first property of this object is simply named
'card-headline' property is wrapped in single quotes. The problem here is that the second definition contains a hyphen.
The downside is that you cannot access this second property directly in the form of
So instead of
style.card-headline the property needs to be accessed through
The problem now is that your web part is not type safe anymore because it is very challenging to evaluate all the bracket notations used in your web part. Also, you won’t get any warning in the editor if you rename a class or have properties that don’t exist anymore.
The SharePoint Framework issues a simple warning in the console that gives the hint that camel-cased class names might be a better option for specific class names.
Renaming all the classes is a valid option but not a practical. If you already have a well-proven web development guidance in your company that uses one of the previously mentioned naming conventions you don’t like to set up exclusive guide for CSS naming conventions for web parts.
In theory, you can mix the dot notation with the bracket notation when you add the style definitions to your web part code. From my point of view, you should be consistent what to use and mix both notations is not a good option. If the class names might contain hyphens, always use the bracket notation, but you will loose some of the type-safe benefits.
If you just use simple names always use the dot notation, because otherwise, your code becomes hard to read. If none of these options does work that well you can disable all this auto-postfixing SASS compilation.
In this case, you need to make sure that your style definitions are unique. The easiest way to accomplish this is to define a base class on the web part container.
Then you can simply wrap all your CSS code with this class name.
The last option is not to use any CSS-specific code in the SharePoint framework at all. In my project, I always have a style guide that already has its clear styling rules, and naming conventions included. This style guide then acts as an external custom tailored framework for my clients. It is easy to deploy the style sheet used to the CDN and reference as an external resource.
The SharePoint framework web part then only contains the business logic and the components used for rendering. The style definition, in this case, will be utilised like a global design asset.
I like to know what your thoughts on this are so, please feel free to give me feedback.