v1.2.0

New options Object & Generic API

v1.2.0 (2025-06-12)

✨ New Features

Support for options object in stringifyCSSProperties and stringifyStyleMap:

stringifyCSSProperties(style, {
  important: true,
  unit: 'em',
});

✅ Fully backward compatible: you can still pass true for important statement as in previous versions.

⚠️ However, using an options object is now recommended for clarity and future extensibility.

Inject important statment

Before

stringifyCSSProperties(style, true); // still supported

After

stringifyCSSProperties(style, { important: true });

Set css units for numeric values

stringifyCSSProperties(
  {
    padding: 10,
    fontSize: 1.6,
  },
  {
    unit: { fontSize: "rem" }, // use string (e.g. { unit: 'rem' }) to set common unit for all numeric values
  }
);
// Output: "padding:10px;font-size:1.6rem;"

New API

Types

type StyleMap = Record<string, CSSProperties>;

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>;
};

type StyleDeclaration = Record<string, string | number>;

type StyleRule<T extends object = StyleDeclaration> = Record<string, T>;

Functions

function stringifyCSSProperties(
  cssProperties: CSSProperties,
  optionsOrImportant?: StringifyOptions<CSSProperties> | boolean
): string;

function stringifyStyleMap(
  styleMap: StyleMap,
  optionsOrImportant?: StringifyOptions<CSSProperties> | boolean
): string;

Generic

function stringifyStyleDeclaration<T extends object = StyleDeclaration>(
  styleDeclaration: T,
  options?: StringifyOptions<T>
): string;

function stringifyStyleRule<T extends object = StyleDeclaration>(
  styleRule: StyleRule<T>,
  options?: StringifyOptions<T>
): string;

🤖 What's Changed

• Update dependencies by @arkarlov in #13
• Add Generics and options arg by @arkarlov in #14

Full Changelog: v1.1.1...v1.2.0

v1.1.1

Handle undefined CSS property values

v1.1.1 (2025-05-15)

This patch release improves robustness by gracefully handling undefined values in CSSProperties. Previously, explicitly setting a property to undefined would throw an error during stringification.

✅ Fixed

Avoid crashes from undefined property values in stringifyCSSProperties

Now, properties with undefined values are silently skipped instead of throwing an error.

stringifyCSSProperties({
  color: undefined,
  padding: 10,
});

Before

// Throws: "Invalid input: value of 'cssProperties' must be string or number."

After

// Output: "padding:10px;"

📄 Other

🧪 Added unit tests for undefined values

📝 Added a markdown doc with manual publishing instructions

🔗 Related

Issue: Support undefined for values #11

Thanks @dbondarchuk for bringing this up! 🙌

---

🤖 What's Changed

• build(deps-dev): bump vitest from 2.1.1 to 2.1.9 by @dependabot in #9
• update dependencies by @arkarlov in #10
• Fix: Skip explicit undefined values in stringifyCSSProperties by @arkarlov in #12

New Contributors

• @dependabot made their first contribution in #9

Full Changelog: v1.1.0...v1.1.1

v1.1.0

Cleaner, Leaner CSS

v1.1.0 (2024-10-24)

✨ Stripped spaces between CSS rules.

Whitespace between CSS rules has been removed for more compact output.

stringifyCSSProperties({
  flex: 1,
  padding: 20,
  backgroundColor: "teal",
});

Before

// Output: "flex:1; padding:20px; background-color:teal;"

After

// Output: "flex:1;padding:20px;background-color:teal;"

🧹 Removed empty CSS rules from the output in stringifyStyleMap.

Previously, passing 'selector': {} resulted in selector{}, but now such rules are excluded from the result.

stringifyStyleMap({
      header: { color: "teal" },
      main: {},
      footer: { color: "teal" },
    });

Before

// Output: "header{color:teal;} main{} footer{color:teal;}"

After

// Output: "header{color:teal;}footer{color:teal;}"

✂️ Trimmed unnecessary spaces in CSS selectors.

Extra spaces around combinators (e.g., >, +, ~) are now removed.

stringifyStyleMap({
  "#root ul.my-list > li": {
    padding: 10,
  },
});

Before

// Output: "#root ul.my-list > li{padding:10px;}"

After

// Output: "#root ul.my-list>li{padding:10px;}"

---

🤖 What's Changed

• Add tests by @arkarlov in #1
• Add test github action by @arkarlov in #6
• Update tests.yml by @arkarlov in #7
• Trim css strings and selectors by @arkarlov in #8

Full Changelog: v1.0.0...v1.1.0

v1.0.0

Initial Release

v1.0.0 (2024-09-24)

🎉 Highlights

This is the first release of the react-style-stringify package.
It provides utility functions to convert CSS objects into string representations, making it easier to work with styles in React projects and beyond.

✨ Key Features

Converts a CSSProperties object into a CSS string.
Converts a Record<string, CSSProperties> map into a CSS string.
Automatically adds units (e.g., px) to numeric CSS properties when necessary.
Allows injecting !important for all properties.
Supports both CommonJS and ESModules.

📦 Installation

npm install react-style-stringify

or

yarn add react-style-stringify

☝️ Note: You need to install @types/react if you're using TypeScript without React.

🚀 Usage

Import utils:

import {
  stringifyCSSProperties,
  stringifyStyleMap,
} from "react-style-stringify";

Convert a single CSSProperties object:

const cssString = stringifyCSSProperties({
  flex: 1,
  padding: 20,
  backgroundColor: "teal",
});
// Output: "flex:1; padding:20px; background-color:teal;"

Convert a Record<string, CSSProperties> object:

const cssMapString = stringifyStyleMap({
  p: {
    margin: 0,
    color: "teal",
  },
  "#root ul.my-list > li": {
    padding: 10,
  },
});
// Output: "p{margin:0; color:teal;} #root ul.my-list > li{padding:10px;}"

Inject !important into CSS string:

const cssString = stringifyCSSProperties(
  {
    flex: 1,
    padding: 20,
    backgroundColor: "teal",
  },
  true
);
// Output: "flex:1!important; padding:20px!important; background-color:teal!important;"

const cssMapString = stringifyStyleMap(
  {
    p: {
      margin: 0,
      color: "teal",
    },
    "#root ul.my-list > li": {
      padding: 10,
    },
  },
  true
);
// Output: "p{margin:0!important; color:teal!important;} #root ul.my-list > li{padding:10px!important;}"

🛠️ Supported Environments

React / TypeScript (with @types/react for CSSProperties type support)
Vanilla JavaScript

---

💡Feel free to contribute by submitting Pull Requests and Issues.