{"id":15584,"library":"cssesc","title":"cssesc: CSS String and Identifier Escaping","description":"cssesc is a JavaScript utility library designed for safely escaping arbitrary strings and identifiers for use within CSS. It specializes in producing the shortest possible valid ASCII-only escape sequences, making it efficient for various web development scenarios. Currently at stable version 3.0.0, it offers more granular control than the native `CSS.escape()` method or its polyfills. Key differentiators include the ability to specify if the output is intended for a CSS string literal or a CSS identifier, and control over quote preferences for string wrapping. Its release cadence is typically measured, reflecting its nature as a focused utility library with a stable API. It declares compatibility with Node.js versions 4 and higher, making it widely compatible, though modern usage typically occurs on much newer environments.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/mathiasbynens/cssesc","tags":["javascript","css","escape","identifier","string","tool"],"install":[{"cmd":"npm install cssesc","lang":"bash","label":"npm"},{"cmd":"yarn add cssesc","lang":"bash","label":"yarn"},{"cmd":"pnpm add cssesc","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library primarily exposes a default function, not named exports, for ESM environments.","wrong":"import { cssesc } from 'cssesc';","symbol":"cssesc","correct":"import cssesc from 'cssesc';"},{"note":"This is the standard CommonJS import pattern, as shown in the package's documentation.","symbol":"cssesc","correct":"const cssesc = require('cssesc');"},{"note":"While the library primarily exports a default function, TypeScript users might find type definitions for 'Options' useful if shipped with the package, typically as a named export.","wrong":"type Options = { isIdentifier?: boolean; quotes?: 'single' | 'double'; wrap?: boolean; }; // Manual definition","symbol":"Options","correct":"import cssesc, { Options } from 'cssesc';"}],"quickstart":{"code":"import cssesc from 'cssesc';\n\nconsole.log('--- Escaping for CSS String Literal ---');\nconst unsafeString = 'Hello, world! I ♥ JavaScript and \"quotes\".';\nconst escapedString = cssesc(unsafeString);\nconsole.log(`Original: \"${unsafeString}\"\\nEscaped:  '${escapedString}'`);\n// Expected: 'Hello, world! I \\2665  JavaScript and \\\"quotes\\\".'\n\nconsole.log('\\n--- Escaping for CSS Identifier ---');\nconst unsafeIdentifier = '1a-b.c d';\nconst escapedIdentifier = cssesc(unsafeIdentifier, { isIdentifier: true });\nconsole.log(`Original: \"${unsafeIdentifier}\"\\nEscaped:  '${escapedIdentifier}'`);\n// Expected: '\\31 a-b\\.c\\ d'\n\nconsole.log('\\n--- Escaping with Double Quotes and Wrapping ---');\nconst anotherUnsafeString = 'My ID is #foo/bar and it has \\'single\\' quotes.';\nconst wrappedDoubleQuoteEscaped = cssesc(anotherUnsafeString, {\n  quotes: 'double',\n  wrap: true\n});\nconsole.log(`Original: \"${anotherUnsafeString}\"\\nEscaped:  ${wrappedDoubleQuoteEscaped}`);\n// Expected: \"My ID is #foo/bar and it has 'single' quotes.\"\n\nconsole.log('\\n--- Escaping a non-ASCII character (emojis) ---');\nconst emojiString = 'User😊Name';\nconst escapedEmoji = cssesc(emojiString, { isIdentifier: true });\nconsole.log(`Original: \"${emojiString}\"\\nEscaped:  '${escapedEmoji}'`);\n// Expected: 'User\\1F60A Name'","lang":"javascript","description":"Demonstrates basic CSS string and identifier escaping using `cssesc` with various options for quote types and wrapping, including handling of non-ASCII characters."},"warnings":[{"fix":"Always pass `{ isIdentifier: true }` in the options object when escaping a value intended for a CSS identifier. For example: `cssesc('123abc', { isIdentifier: true })`.","message":"Incorrectly using the output of `cssesc` for a CSS identifier (e.g., class names, IDs) without setting the `isIdentifier: true` option will lead to improperly escaped CSS that breaks selectors or other identifier contexts. The default behavior is for CSS string literals.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"For ESM modules, use `import cssesc from 'cssesc';`. Avoid `import { cssesc } from 'cssesc';` or attempting to `require` in an ESM context.","message":"When migrating to modern JavaScript module systems (ESM), ensure you use the `import cssesc from 'cssesc';` syntax. The package's documentation prominently features `require('cssesc')`, which is for CommonJS environments.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your project uses a actively maintained Node.js LTS version (e.g., Node.js 18 or 20) for optimal security and performance.","message":"The `package.json` specifies `engines.node: >=4`. While technically compatible with very old Node.js versions, running `cssesc` in such environments is discouraged due to potential security vulnerabilities and lack of modern features in the Node.js runtime itself. Always use a currently supported Node.js LTS version.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"For ESM, use `import cssesc from 'cssesc';`. For CommonJS, use `const cssesc = require('cssesc');`. If using `import * as cssescModule from 'cssesc';`, call it as `cssescModule.default(...)`.","cause":"Attempting to call `cssesc` as a named export (`{ cssesc }`) when it's primarily a default export, or trying to call it on a module object when using `import * as cssesc from 'cssesc';` without accessing `.default`.","error":"TypeError: cssesc is not a function"},{"fix":"Change your import statement to `import cssesc from 'cssesc';` to correctly import the default exported function.","cause":"This error occurs in ESM when attempting to destructure `cssesc` as a named export (`import { cssesc } from 'cssesc';`) while the package only provides a default export for its main functionality.","error":"Error: Module 'cssesc' does not provide an export named 'cssesc'"},{"fix":"When escaping values intended for CSS identifiers (like class names, IDs, custom property names), always use `cssesc(value, { isIdentifier: true })`. This ensures characters like initial digits or special symbols are correctly escaped for identifier rules.","cause":"The input string was escaped using `cssesc()` without the `isIdentifier: true` option, leading to incorrect escaping for CSS identifiers (e.g., `.` or `-` not being escaped when they should be at the start of a sequence).","error":"CSS selector for ID or class with special characters doesn't work"}],"ecosystem":"npm"}