react-style-stringify/dist/index.d.ts

A utility for converting React CSSProperties and style maps into CSS strings, designed to simplify the management of inline styles in HTML email templates and React projects.

import { CSSProperties } from 'react';

type CSSUnit = "px" | "em" | "rem" | "vw" | "vh" | "%";
type CSSUnitMap<K extends PropertyKey = string> = {
    [P in K]?: CSSUnit;
};
type StringifyOptions<T extends object = Record<string, string | number>> = {
    important?: boolean;
    unit?: CSSUnit | CSSUnitMap<keyof T>;
};

/**
 * Converts a CSSProperties object into a CSS string.
 *
 * @param {CSSProperties} cssProperties - An object representing CSS declarations, where keys are camelCased property names and values are the corresponding CSS values.
 *   - CSSProperties type comes from `@types/react` and is commonly used for inline styles in React components.
 *
 * @param {StringifyOptions | boolean} [optionsOrImportant=false] - Either a boolean indicating whether to append `!important` to each property,
 *                                                                  or an object with more detailed formatting options:
 *   - `important` (boolean): If true, appends `!important` to each property.
 *   - `unit` (object | string): A unit (like `'em'`, `'%'`, etc.) to apply to numeric values, or a map of per-property units.
 *     If a unit is not provided, `'px'` is used by default for numeric values (except for unitless properties).
 *
 * @returns {string} A formatted CSS string where each property is converted to kebab-case, units are added where necessary,
 *                   and `!important` is appended if specified.
 *
 * @throws {TypeError} Throws if `cssProperties` is not a non-null object.
 */
declare function stringifyCSSProperties(cssProperties: CSSProperties, optionsOrImportant?: StringifyOptions<CSSProperties> | boolean): string;
type StyleMap = Record<string, CSSProperties>;
/**
 * Converts a `StyleMap` (a map of CSS selectors to React `CSSProperties`) into a string of CSS rules.
 *
 * @param {StyleMap} styleMap - An object where keys are CSS selectors and values are React-style `CSSProperties` objects (camelCased CSS declarations).
 * @param {StringifyOptions | boolean} [optionsOrImportant=false] - Either a boolean flag to apply `!important` to all declarations, or an options object that may include `important` and per-property unit definitions.
 *
 * @returns {string} A formatted CSS string where each selector is followed by its corresponding declarations.
 *                   Properties are converted to kebab-case and numeric values are suffixed with appropriate units unless the property is unitless.
 *
 * @throws {TypeError} Throws if `cssProperties` is not a non-null object.
 */
declare function stringifyStyleMap(styleMap: StyleMap, optionsOrImportant?: StringifyOptions<CSSProperties> | boolean): string;

type StyleDeclaration = Record<string, string | number>;
/**
 * Converts a StyleDeclaration object into a CSS string.
 *
 * @param {object} styleDeclaration - An object representing a CSS declaration block, where keys are camelCased CSS property names and values are the corresponding CSS values (strings or numbers).
 * @param {StringifyOptions<T>} [options] - Optional configuration object:
 *   - `important` — If set to `true`, appends `!important` to each CSS declaration.
 *   - `unit` — A CSS unit or a map of property keys to units:
 *     - If a string is provided (e.g. `'em'`), it will be used as the unit for all numeric properties.
 *     - If a map is provided (e.g. `{ width: 'rem' }`), the unit will be applied per numeric property.
 *     - If a property has a numeric value and no specific unit is defined in the map, `'px'` will be used by default.
 *
 * @returns {string} A formatted CSS string where:
 *   - Keys are converted from camelCase to kebab-case.
 *   - Units are added to numeric values as specified, or `'px'` by default.
 *   - Each declaration ends with a semicolon.
 *   - `!important` is appended if the `important` flag is set.
 *
 * @throws {TypeError} Throws if the `styleDeclaration` argument is not a non-null object.
 */
declare function stringifyStyleDeclaration<T extends object = StyleDeclaration>(styleDeclaration: T, options?: StringifyOptions<T>): string;

type StyleRule<T extends object = StyleDeclaration> = Record<string, T>;
/**
 * Converts a style rule object into a CSS string.
 *
 * @template T - The type representing CSS property keys and values used in the style declarations.
 *
 * @param {StyleRule<T>} styleRule - An object where keys are CSS selectors and values are style declarations
 *                                   (objects mapping CSS properties to values).
 * @param {StringifyOptions<T>} [options] - Optional settings controlling how declarations are stringified,
 *                                         such as appending `!important` or units.
 *
 *
 * @returns {string} A CSS string where each selector and its corresponding declarations are formatted properly.
 *                   Empty declarations are skipped.
 *
 * @throws {TypeError} Throws if the `styleRule` argument is not a non-null object.
 */
declare function stringifyStyleRule<T extends object = StyleDeclaration>(styleRule: StyleRule<T>, options?: StringifyOptions<T>): string;

export { type CSSUnit, type CSSUnitMap, type StringifyOptions, type StyleDeclaration, type StyleMap, type StyleRule, stringifyCSSProperties, stringifyStyleDeclaration, stringifyStyleMap, stringifyStyleRule };