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

style-merging.mddocs/

Style Merging

Core functionality for converting JavaScript style objects into CSS class names with support for pseudo-selectors, media queries, and complex style combinations.

Capabilities

Basic Style Merging

Converts style objects and class names into a single CSS class name.

/**
 * Concatenates style objects and class names into a single CSS class name
 * @param args - Style objects, class names, arrays, or falsy values
 * @returns Generated CSS class name
 */
function mergeStyles(...args: IStyle[]): string;

// Shadow DOM overload
function mergeStyles(shadowConfig: ShadowConfig, ...args: IStyle[]): string;

Usage Examples:

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

// Basic styles
const className = mergeStyles({
  color: "red",
  fontSize: "14px"
});

// With pseudo-selectors
const hoverStyle = mergeStyles({
  color: "blue",
  ":hover": {
    color: "darkblue",
    cursor: "pointer"
  },
  ":focus": {
    outline: "2px solid blue"
  }
});

// Media queries
const responsiveStyle = mergeStyles({
  fontSize: "16px",
  "@media (max-width: 768px)": {
    fontSize: "14px"
  }
});

// Combining multiple styles
const combinedStyle = mergeStyles(
  { backgroundColor: "white" },
  { padding: "10px" },
  someConditionalStyle && { border: "1px solid gray" }
);

// Shadow DOM usage
import { makeShadowConfig } from "@fluentui/merge-styles";

const shadowConfig = makeShadowConfig("my-component", true);
const shadowClassName = mergeStyles(shadowConfig, {
  color: "blue",
  padding: "10px"
});

Advanced Style Merging with Options

Style merging with explicit configuration options for RTL support and Shadow DOM.

/**
 * Concatenates styles with explicit options
 * @param args - Style arguments or array of style arguments
 * @param options - Configuration options for style processing
 * @returns Generated CSS class name
 */
function mergeCss(
  args: IStyle | IStyle[], 
  options?: IStyleOptions
): string;

Usage Examples:

import { mergeCss, makeShadowConfig } from "@fluentui/merge-styles";

// With RTL support
const className = mergeCss(
  { marginLeft: "10px", textAlign: "left" },
  { rtl: true }
);

// With Shadow DOM configuration
const shadowConfig = makeShadowConfig("myComponent", true);
const shadowClassName = mergeCss(
  { color: "red" },
  { shadowConfig }
);

Style Array Processing

Handles arrays of styles with automatic flattening and filtering of falsy values.

interface IStyleBaseArray extends Array<IStyle> {}

Usage Examples:

// Array of styles
const styles = [
  { color: "red" },
  { fontSize: "14px" },
  isActive && { fontWeight: "bold" },
  isHovered && { textDecoration: "underline" }
];

const className = mergeStyles(...styles);

// Nested arrays are flattened
const nestedStyles = [
  [{ margin: "5px" }, { padding: "5px" }],
  { border: "1px solid gray" }
];

const nestedClassName = mergeStyles(...nestedStyles);

Core Types

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

interface IRawStyle extends IRawStyleBase {
  [key: string]: any;
  displayName?: string;
  /** @deprecated Use nested syntax instead */
  selectors?: { [key: string]: IStyle };
}

interface IStyleOptions {
  /** Enable right-to-left style transformations */
  rtl?: boolean;
  /** Shadow DOM configuration */
  shadowConfig?: ShadowConfig;
  /** Custom stylesheet instance */
  stylesheet?: Stylesheet;
  /** Multiplier for CSS specificity */
  specificityMultiplier?: number;
}

Pseudo-Selectors and Media Queries

Style objects support CSS pseudo-selectors and media queries as nested properties:

const advancedStyle = mergeStyles({
  // Base styles
  color: "black",
  padding: "10px",
  
  // Pseudo-selectors
  ":hover": {
    color: "blue"
  },
  ":focus": {
    outline: "2px solid blue"
  },
  ":active": {
    transform: "scale(0.98)"
  },
  
  // Pseudo-elements
  "::before": {
    content: "''",
    display: "block",
    width: "100%",
    height: "2px",
    backgroundColor: "blue"
  },
  
  // Media queries
  "@media (max-width: 768px)": {
    padding: "5px",
    fontSize: "14px"
  },
  
  // Complex selectors
  "& .child": {
    marginLeft: "10px"
  },
  
  // Multiple selectors
  "&:hover, &:focus": {
    boxShadow: "0 2px 4px rgba(0,0,0,0.1)"
  }
});

RTL (Right-to-Left) Support

Automatic style flipping for RTL languages:

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

// Enable RTL globally
setRTL(true);

// These styles will be automatically flipped
const rtlStyle = mergeStyles({
  marginLeft: "10px",    // becomes marginRight: "10px"
  textAlign: "left",     // becomes textAlign: "right"
  borderLeft: "1px solid red" // becomes borderRight: "1px solid red"
});