@microsoft/load-themed-styles

What is @microsoft/load-themed-styles?

@microsoft/load-themed-styles is a utility library for loading and applying CSS styles dynamically in a way that supports theming. It is particularly useful in scenarios where styles need to be adjusted based on a theme, such as in web applications that support multiple themes or dynamic style changes.

What are @microsoft/load-themed-styles's main functionalities?

Load Styles

This feature allows you to load CSS styles dynamically. The `loadStyles` function takes a string of CSS and injects it into the document's head.

const { loadStyles } = require('@microsoft/load-themed-styles');

loadStyles('.myClass { color: red; }');

Load Themed Styles

This feature allows you to load styles that are theme-aware. The `loadTheme` function sets the theme, and `loadStyles` can then use theme tokens to apply the correct styles based on the current theme.

const { loadTheme, loadStyles } = require('@microsoft/load-themed-styles');

const theme = {
  palette: {
    themePrimary: '#0078d4',
    themeSecondary: '#2b88d8'
  }
};

loadTheme(theme);
loadStyles('.myClass { color: [theme:themePrimary]; }');

Clear Styles

This feature allows you to clear all dynamically loaded styles. The `clearStyles` function removes all styles that were injected using `loadStyles`.

const { clearStyles } = require('@microsoft/load-themed-styles');

clearStyles();

Other packages similar to @microsoft/load-themed-styles

styled-components

styled-components is a library for React and React Native that allows you to use component-level styles in your application. It uses tagged template literals to style components. Unlike @microsoft/load-themed-styles, styled-components is more focused on component-based styling and offers a more modern approach to styling in React applications.

emotion

Emotion is a performant and flexible CSS-in-JS library. It allows you to style applications quickly with string or object styles. Emotion provides powerful and flexible theming capabilities, similar to @microsoft/load-themed-styles, but it is more focused on the CSS-in-JS paradigm and offers a broader range of features for styling React components.

jss

JSS is an authoring tool for CSS which uses JavaScript as a host language. It allows you to describe styles in a declarative, maintainable, and reusable way. JSS supports theming and dynamic styles, similar to @microsoft/load-themed-styles, but it is more general-purpose and can be used with various frameworks, not just React.

README

@microsoft/load-themed-styles

Loads a string of style rules, but supports detokenizing theme constants built within it.

Install

Install with npm

$ npm install --save @microsoft/load-themed-styles

Usage

To load a given string of styles, you can do this in TypeScript or ES6:

import { loadStyles } from '@microsoft/load-themed-styles';

loadStyles('body { background: red; }');

This will register any set of styles given. However, in the above example the color is hardcoded to red. To make this theme-able, replace it with the string token in this format:

"[theme:{variableName}, default:{defaultValue}]"

For example:

loadStyles('body { background: "[theme:primaryBackgroundColor, default: blue]"');

When loading, the background will use the default value, blue. Providing your own theme values using the loadTheme function:

import { loadStyles, loadTheme } from '@microsoft/load-themed-styles';

loadTheme({
  primaryBackgroundColor: "#EAEAEA"
});

loadStyles('body { background: "[theme:primaryBackgroundColor, default: #FFAAFA]"');

This will register #EAEAEA as the body's background color. If you call loadTheme again after styles have already been registered, it will replace the style elements with retokenized values.

Security considerations

In order for style elements to be added to the DOM, a nonce attribute may need to be attached to the elements to adhere to a CSP requirements. To provide the value, you can specify the nonce value by defining a CSPSettings object on the page in global scope:

window.CSPSettings = {
  nonce: 'nonce'
};

Links

• CHANGELOG.md - Find out what's new in the latest version

@microsoft/load-themed-styles is part of the Rush Stack family of projects.