{"id":10695,"library":"css.escape","title":"CSS.escape Polyfill","description":"This package provides a robust polyfill for the `CSS.escape` utility method, as defined in the CSSOM specification. It ensures that CSS identifiers can be safely escaped, preventing syntax errors when dealing with strings that might contain special CSS characters (e.g., spaces, hashes, dots). Currently at version 1.5.1, the package appears to be in a maintenance state with its last update several years ago, as the `CSS.escape` method is now widely supported natively in modern browsers. For applications requiring more advanced escaping options, such as handling excessive whitespace or custom output formats, the `cssesc` package is recommended as a more powerful alternative.","status":"maintenance","version":"1.5.1","language":"javascript","source_language":"en","source_url":"https://github.com/mathiasbynens/CSS.escape","tags":["javascript","string","unicode","identifier","css","cssom","polyfill"],"install":[{"cmd":"npm install css.escape","lang":"bash","label":"npm"},{"cmd":"yarn add css.escape","lang":"bash","label":"yarn"},{"cmd":"pnpm add css.escape","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is primarily a global polyfill. In browser environments, include it via a script tag to add `CSS.escape` to the global `CSS` object. It does not provide named ES module exports.","wrong":"import { escape } from 'css.escape'","symbol":"CSS.escape (global in browsers)","correct":"<script src=\"css.escape.js\"></script>"},{"note":"In Node.js, requiring the package executes the polyfill, modifying the global `CSS` object. It does not export any direct symbols, so it's a side-effect import. It is a CommonJS module.","wrong":"import 'css.escape';","symbol":"require (for Node.js)","correct":"require('css.escape');"}],"quickstart":{"code":"require('css.escape');\n\n// Verify that CSS.escape is available\nif (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {\n  const escapedId = CSS.escape('.my-class#with spaces!');\n  console.log(`Original: .my-class#with spaces!`);\n  console.log(`Escaped: ${escapedId}`); // Expected: \\.my-class\\#with\\ spaces\\!\n\n  const escapedSelector = `#${CSS.escape('user id')}`;\n  console.log(`Selector for 'user id': ${escapedSelector}`); // Expected: #user\\ id\n\n  const trickyString = '123_abc-def';\n  console.log(`Escaped: ${CSS.escape(trickyString)}`); // Expected: 123_abc-def (no change needed)\n} else {\n  console.error('CSS.escape is not available after polyfill attempt.');\n}","lang":"javascript","description":"Demonstrates how to include the `css.escape` polyfill in a Node.js environment using CommonJS `require` and then utilize the globally available `CSS.escape` method to safely escape strings for use in CSS selectors or identifiers."},"warnings":[{"fix":"For modern browser targets, consider removing this polyfill. For broader compatibility including older browsers, ensure proper loading order if other polyfills or browser features might conflict.","message":"This package provides a polyfill for `CSS.escape`, which is now natively supported in all evergreen browsers. Using this polyfill in modern environments is largely redundant and can introduce unnecessary script weight or potential conflicts if a browser's native implementation differs slightly.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"In Node.js, use `require('css.escape');`. In browser environments, include `css.escape.js` via a `<script>` tag. The package modifies the global `CSS` object and does not export named symbols.","message":"This polyfill exclusively supports CommonJS (`require()`) for Node.js environments and global script inclusion for browsers. It does not provide ES Module exports (`import`). Attempting to use `import` will result in module resolution errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Evaluate whether `cssesc` is a better fit for your project if active development, additional features, or continued maintenance are critical concerns.","message":"The `css.escape` package has not been updated in several years (last publish v1.5.1 in 2017). While it functions as intended for its polyfill purpose, it receives no active maintenance or updates. For new projects or those requiring more advanced string escaping features (e.g., handling excessive whitespace, customizable output), the `cssesc` package is a more actively maintained and feature-rich alternative.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the `css.escape` script or `require('css.escape')` call is executed before attempting to access `CSS.escape`. In Node.js, confirm that the global `CSS` object is accessible in your execution environment.","cause":"The `css.escape` polyfill relies on a global `CSS` object. This error typically occurs when the polyfill script hasn't been executed or is run in an environment where the global `CSS` object is not available (e.g., some specialized Node.js contexts without a browser-like global scope, or before the polyfill loads).","error":"ReferenceError: CSS is not defined"},{"fix":"Verify that `css.escape` is loaded and executed correctly without conflicts. Check for other scripts that might define or modify `CSS` after `css.escape` has run. Ensure `require('css.escape')` is at the top of your module or the script tag is placed appropriately.","cause":"This indicates that while the `CSS` object might exist, the `escape` method was not successfully added to it, or it was potentially overwritten by another script or polyfill.","error":"TypeError: CSS.escape is not a function"},{"fix":"In Node.js, replace `import 'css.escape';` with `require('css.escape');`. If you are in an ES module context, consider using dynamic `import()` (e.g., `await import('css.escape')`) for specific scenarios, or preferably, use the `cssesc` package which offers proper ESM support. For browser environments, use a traditional `<script>` tag.","cause":"The `css.escape` package is a CommonJS module and does not expose ES Module exports. Attempting to use `import` syntax directly will result in module resolution errors in Node.js or browser bundlers expecting ESM.","error":"SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm"}