NPM Version npm bundle size Module type NPM Type Definitions NPM Downloads
A utility for converting React CSSProperties objects or Record<string, CSSProperties> into CSS strings.
This utility was originally created to simplify the process of adding inline CSS styles to HTML email templates in a React project. Previously, all styles were written as plain strings, which became unmanageable as the project grew. To make styles more maintainable and consistent, this utility was developed to convert React CSSProperties objects into CSS strings, streamlining the process of embedding styles in the final HTML before sending emails.
- Converts a single
CSSPropertiesobject to a CSS string. - Converts a
Record<string, CSSProperties>map to a CSS string. - Automatically adds units (
pxby default) for numeric values. - Optionally injects the
!importantstatement for each css declaration.
npm install react-style-stringify
or
yarn add react-style-stringify
Tip
This package uses the CSSProperties type from @types/react.
If you're working with TypeScript and don't use React, install @types/react.
import { stringifyCSSProperties, stringifyStyleMap, } from "react-style-stringify";
const cssString = stringifyCSSProperties({ flex: 1, padding: 20, backgroundColor: "teal", }); // Output: "flex:1;padding:20px;background-color:teal;" const importantCssString = stringifyCSSProperties( { flex: 1, padding: 20, backgroundColor: "teal", }, { important: true } // `true` in versions <= 1.1.1 ); // Output: "flex:1!important;padding:20px!important;background-color:teal!important;" const cssStringWtihDefinedUnit = stringifyCSSProperties( { padding: 10, fontSize: 1.6, }, { unit: "em", } ); // Output: "padding:10em;font-size:1.6em;" const cssStringWtihDefinedUnitMap = stringifyCSSProperties( { padding: 10, fontSize: 1.6, }, { unit: { fontSize: "rem" }, } ); // Output: "padding:10px;font-size:1.6rem;"
Warning
In versions <= 1.1.1, only true was accepted as the second argument.
As of v1.2.0, the options object { important: true } is recommended.
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;}"
Note
The options argument is forwarded internally to stringifyCSSProperties, so all options (like important or unit) work the same way.
import { stringifyStyleDeclaration, stringifyStyleRule, } from "react-style-stringify"; type MyStyles = { padding: string | number; fontSize: number; "--my-custom-prop": string; }; stringifyStyleDeclaration<Partial<MyStyles>>({ padding: 20, "--my-custom-prop": "brown", }) // Output: "padding:20px;--my-custom-prop:brown;" stringifyStyleRule<Partial<MyStyles>>({ ".container": { padding: 20, "--my-custom-prop": "brown", }, }) // Output: ".container{padding:20px;--my-custom-prop:brown;}"
Note
The options argument works the same way as for stringifyCSSProperties and stringifyStyleMap.
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>;
function stringifyCSSProperties( cssProperties: CSSProperties, optionsOrImportant?: StringifyOptions<CSSProperties> | boolean ): string; function stringifyStyleMap( styleMap: StyleMap, optionsOrImportant?: StringifyOptions<CSSProperties> | boolean ): string;
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;
- @emotion/unitless : Handles checking for CSS properties that are unitless (e.g.,
line-height,z-index, etc.).
- @types/react : The package uses React's
CSSPropertiestype for defining style objects.
Contributions are welcome! If you have ideas or improvements, feel free to open an issue or submit a pull request.
- Fork the repository.
- Create a new branch (
git checkout -b feature-name). - Make your changes and commit (
git commit -am 'Add new feature'). - Push to the branch (
git push origin feature-name). - Create a pull request.
Please make sure your code adheres to the project's coding standards and passes the existing tests.