or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcss-features.mdindex.mdstyle-merging.mdstyle-sets.mdstylesheet-management.md
tile.json

index.mddocs/

@fluentui/merge-styles

@fluentui/merge-styles is a high-performance CSS-in-JavaScript library that provides runtime utilities for dynamically generating CSS classes and style sets. It offers automatic class name generation, pseudo-selector support, media queries, RTL (right-to-left) language support, vendor prefixing, and complete TypeScript type safety.

Package Information

  • Package Name: @fluentui/merge-styles
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @fluentui/merge-styles

Core Imports

import { mergeStyles, mergeStyleSets, IStyle, IStyleSet } from "@fluentui/merge-styles";

Individual imports (tree-shaking friendly):

import { mergeStyles } from "@fluentui/merge-styles/lib/mergeStyles";
import { mergeStyleSets } from "@fluentui/merge-styles/lib/mergeStyleSets";
import { fontFace } from "@fluentui/merge-styles/lib/fontFace";
import { keyframes } from "@fluentui/merge-styles/lib/keyframes";

For server-side rendering:

import { renderStatic } from "@fluentui/merge-styles/lib/server";

For CommonJS:

const { mergeStyles, mergeStyleSets } = require("@fluentui/merge-styles");
const { renderStatic } = require("@fluentui/merge-styles/lib/server");

Basic Usage

import { mergeStyles, mergeStyleSets } from "@fluentui/merge-styles";

// Basic style merging - returns CSS class name
const className = mergeStyles({
  color: "red",
  fontSize: "14px",
  ":hover": {
    color: "blue"
  }
});

// Style set merging - returns object with class names
const classNames = mergeStyleSets({
  container: {
    padding: "10px",
    backgroundColor: "white"
  },
  header: {
    fontSize: "18px",
    fontWeight: "bold"
  }
});

// Usage: classNames.container, classNames.header

Architecture

@fluentui/merge-styles is built around several key components:

  • Style Processing Engine: Core merging logic that converts JavaScript style objects into CSS classes
  • Stylesheet Management: Stylesheet and ShadowDomStylesheet classes for CSS rule injection and caching
  • Type System: Complete TypeScript interfaces for CSS properties, style objects, and configuration
  • RTL Support: Automatic style flipping for right-to-left languages with setRTL()
  • Shadow DOM Support: Specialized handling for Shadow DOM environments
  • Performance Optimization: Style caching, deduplication, and minimal runtime overhead

Capabilities

Style Merging

Core functionality for converting JavaScript style objects into CSS class names. Supports pseudo-selectors, media queries, and style object arrays.

function mergeStyles(...args: IStyle[]): string;
function mergeCss(args: IStyle | IStyle[], options?: IStyleOptions): string;

Style Merging

Style Set Processing

Advanced functionality for handling collections of related styles with automatic class name generation and type preservation.

function mergeStyleSets<TStyleSet>(
  ...styleSets: Array<IStyleSet | Missing>
): IProcessedStyleSet<TStyleSet>;

function mergeCssSets<TStyleSet>(
  styleSets: Array<IStyleSet | Missing>, 
  options?: IStyleOptions
): IProcessedStyleSet<TStyleSet>;

Style Set Processing

CSS Features

Support for CSS @font-face declarations and @keyframes animations with automatic registration and deduplication.

function fontFace(font: IFontFace): void;
function keyframes(timeline: IKeyframes): string;

CSS Features

Stylesheet Management

Low-level stylesheet management with support for rule injection, caching, and Shadow DOM environments.

class Stylesheet {
  constructor(config?: IStyleSheetConfig);
  insertRule(rule: string, preserve?: boolean): void;
  getClassName(displayName?: string): string;
  getRules(includePreservedRules?: boolean): string;
}

class ShadowDomStylesheet extends Stylesheet {
  static getInstance(shadowConfig?: ShadowConfig): ShadowDomStylesheet;
}

Stylesheet Management

Server-Side Rendering

Server-side rendering utilities for extracting CSS during HTML generation.

function renderStatic(onRender: () => string, namespace?: string): { html: string; css: string };

Configuration and Utilities

Global configuration options, RTL support, Shadow DOM configuration, and utility functions.

function setRTL(isRTL: boolean): void;
function getRTL(): boolean;
function makeShadowConfig(stylesheetKey: string, inShadow: boolean, window?: Window): ShadowConfig;
function concatStyleSets<TStyleSet>(...styleSets: TStyleSet[]): IConcatenatedStyleSet<TStyleSet>;
function concatStyleSetsWithProps<TStyleProps, TStyleSet extends IStyleSetBase>(
  styleProps: TStyleProps,
  ...allStyles: (IStyleFunctionOrObject<TStyleProps, TStyleSet> | undefined)[]
): DeepPartial<TStyleSet>;
function cloneCSSStyleSheet(srcSheet: CSSStyleSheet, targetSheet: CSSStyleSheet): CSSStyleSheet;

Configuration and Utilities

Constants

/** Browser supports constructable stylesheets */
const SUPPORTS_CONSTRUCTABLE_STYLESHEETS: boolean;

/** Browser supports modifying adopted stylesheets */
const SUPPORTS_MODIFYING_ADOPTED_STYLESHEETS: boolean;

/** Default global shadow configuration */
const DEFAULT_SHADOW_CONFIG: ShadowConfig;

/** Global stylesheet key constant */
const GLOBAL_STYLESHEET_KEY = "__global__";

Core Types

type IStyle = IStyleBase | IStyleBaseArray;
type IStyleBase = IRawStyle | string | false | null | undefined;

interface IRawStyle extends IRawStyleBase {
  [key: string]: any;
  displayName?: string;
  selectors?: { [key: string]: IStyle };
}

interface IStyleSet<TStyleSet extends IStyleSetBase = { [key: string]: any }> {
  [P in keyof Omit<TStyleSet, 'subComponentStyles'>]: IStyle;
} & {
  subComponentStyles?: {
    [P in keyof TStyleSet['subComponentStyles']]: IStyleFunctionOrObject<any, any>;
  };
}

interface IProcessedStyleSet<TStyleSet extends IStyleSetBase> {
  [P in keyof Omit<TStyleSet, 'subComponentStyles'>]: string;
} & {
  subComponentStyles: {
    [P in keyof TStyleSet['subComponentStyles']]: Function;
  };
}

interface IStyleOptions {
  rtl?: boolean;
  shadowConfig?: ShadowConfig;
  stylesheet?: Stylesheet;
  specificityMultiplier?: number;
}

interface IStyleSetBase {
  [key: string]: any;
  subComponentStyles?: any;
}

type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends Array<infer U> 
    ? Array<DeepPartial<U>> 
    : T[P] extends object 
      ? DeepPartial<T[P]> 
      : T[P];
};

type IStyleFunctionOrObject<TStylesProps, TStyleSet extends IStyleSetBase> = 
  IStyleFunction<TStylesProps, TStyleSet> | DeepPartial<TStyleSet>;

type IStyleFunction<TStylesProps, TStyleSet extends IStyleSetBase> = 
  (props: TStylesProps) => DeepPartial<TStyleSet>;