or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdfont-animation.mdindex.mdserver-rendering.mdstyle-sets.mdstyling.md
tile.json

tessl/npm-uifabric--merge-styles

Style loading utilities that provide CSS-in-JS functionality with automatic vendor prefixing, RTL support, and server-side rendering capabilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@uifabric/merge-styles@7.20.x

To install, run

npx @tessl/cli install tessl/npm-uifabric--merge-styles@7.20.0

index.mddocs/

Merge Styles

Merge Styles is a CSS-in-JS library that provides utilities for loading styles through JavaScript with performance optimizations. It generates CSS classes dynamically rather than using inline styling, enabling advanced CSS features like pseudo-selectors, media queries, and parent/child relationships. The library is designed for speed and size, weighing only 2.62k gzipped with zero runtime dependencies except tslib.

Package Information

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

Core Imports

import { mergeStyles, mergeStyleSets } from '@uifabric/merge-styles';

For CommonJS:

const { mergeStyles, mergeStyleSets } = require('@uifabric/merge-styles');

Basic Usage

import { mergeStyles, mergeStyleSets } from '@uifabric/merge-styles';

// Single class name generation
const redBackgroundClass = mergeStyles({ 
  background: 'red',
  ':hover': { background: 'darkred' }
});

// Multiple class names from a style set
const classNames = mergeStyleSets({
  root: { 
    background: 'lightblue',
    padding: '10px'
  },
  button: { 
    backgroundColor: 'green',
    color: 'white',
    border: 'none',
    borderRadius: '4px'
  }
});

// Usage in React components
function MyComponent() {
  return (
    <div className={classNames.root}>
      <button className={classNames.button}>Click me</button>
    </div>
  );
}

Architecture

Merge Styles is built around several key design patterns:

  • Dynamic Class Generation: Creates CSS classes at runtime based on JavaScript objects rather than pre-built CSS
  • Memoization: Caches generated classes to avoid duplicate rule registration and improve performance
  • Rule Deduplication: Automatically handles duplicate styles by reusing existing class names
  • RTL Support: Automatically flips CSS properties for right-to-left languages when RTL is enabled
  • Server-Side Rendering: Provides utilities to extract CSS rules during SSR for hydration
  • Vendor Prefixing: Automatically adds necessary vendor prefixes to CSS properties

Capabilities

Core Styling Functions

Primary functions for creating CSS classes from JavaScript style objects, with support for arrays, conditionals, and advanced CSS features.

function mergeStyles(...args: (IStyle | IStyleBaseArray | false | null | undefined)[]): string;

function mergeCss(
  args: (IStyle | IStyleBaseArray | false | null | undefined) | (IStyle | IStyleBaseArray | false | null | undefined)[],
  options?: IStyleOptions
): string;

Core Styling Functions

Style Sets and Concatenation

Functions for managing multiple related styles as sets, concatenating style objects, and working with component style hierarchies.

function mergeStyleSets(...styleSets: Array<IStyleSet | undefined | false | null>): IProcessedStyleSet<any>;

function mergeCssSets(
  styleSets: Array<IStyleSet | undefined | false | null>,
  options?: IStyleOptions
): IProcessedStyleSet<any>;

function concatStyleSets(...styleSets: (IStyleSet | false | null | undefined)[]): IConcatenatedStyleSet<any>;

function concatStyleSetsWithProps<TStyleProps, TStyleSet extends IStyleSet<TStyleSet>>(
  styleProps: TStyleProps,
  ...allStyles: (IStyleFunctionOrObject<TStyleProps, TStyleSet> | undefined)[]
): DeepPartial<TStyleSet>;

Style Sets and Concatenation

Server-Side Rendering

Utilities for rendering styles on the server and extracting CSS rules for client hydration. Note: Server-side rendering functions are available from a separate import path.

// Available from '@uifabric/merge-styles/lib/server'
function renderStatic(onRender: () => string, namespace?: string): { html: string; css: string };

Server-Side Rendering

Font and Animation Utilities

Functions for registering custom fonts and CSS animations using JavaScript objects.

function fontFace(font: IFontFace): void;

function keyframes(timeline: IKeyframes): string;

Font and Animation Utilities

Configuration and State Management

Functions and classes for configuring the library's behavior, managing RTL state, and controlling CSS injection.

function setRTL(isRTL: boolean): void;

class Stylesheet {
  static getInstance(): Stylesheet;
  setConfig(config: IStyleSheetConfig): void;
  insertRule(rule: string, preserve?: boolean): void;
  getRules(forceUpdate?: boolean): string;
  reset(): void;
}

Configuration and State Management

Core Types

type IStyle = IStyleBase | IStyleBaseArray;
type IStyleBase = IRawStyle | string | false | null | undefined;
interface IStyleBaseArray extends Array<IStyle> {}

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

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

type IProcessedStyleSet<TStyleSet extends IStyleSet<TStyleSet>> = {
  [P in keyof Omit<TStyleSet, 'subComponentStyles'>]: string;
} & {
  subComponentStyles: {
    [P in keyof TStyleSet['subComponentStyles']]: __MapToFunctionType<
      TStyleSet['subComponentStyles'] extends infer J ? (P extends keyof J ? J[P] : never) : never
    >;
  };
};

interface IStyleOptions {
  rtl?: boolean;
  specificityMultiplier?: number;
}

interface IStyleSheetConfig {
  injectionMode?: InjectionMode;
  defaultPrefix?: string;
  namespace?: string;
  cspSettings?: ICSPSettings;
}

type IKeyframes = Record<string, IRawStyle>;