{"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,"search_vec":"'3.0.0':50 '4':117 'abil':68 'api':110 'arbitrari':17 'ascii':34 'ascii-on':33 'cadenc':95 'compat':113,123 'control':55,86 'css':2,24,78,83,134 'css.escape':59 'cssesc':1,7 'current':46 'declar':112 'design':13 'develop':44 'differenti':65 'effici':40 'environ':132 'escap':6,16,36,135 'focus':104 'granular':54 'higher':119 'identifi':5,20,84,136 'includ':66 'intend':75 'javascript':10,133 'key':64 'librari':12,106 'liter':80 'make':38,120 'measur':98 'method':60 'modern':125 'much':130 'nativ':58 'natur':101 'newer':131 'node.js':115 'occur':128 'offer':52 'output':73 'polyfil':63 'possibl':31 'prefer':89 'produc':28 'quot':88 'reflect':99 'releas':94 'safe':15 'scenario':45 'sequenc':37 'shortest':30 'special':26 'specifi':70 'stabl':48,109 'string':3,18,79,91,137 'though':124 'tool':138 'typic':97,127 'usag':126 'use':22 'util':11,105 'valid':32 'various':42 'version':49,116 'web':43 'wide':122 'within':23 'wrap':92","created_at":"2026-04-21T17:58:56.735012+00:00","updated_at":"2026-04-21T17:58:56.735012+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":"https://mths.be/cssesc","github":"https://github.com/mathiasbynens/cssesc","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/cssesc","openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-20","install_tag":null}}