CSS.escape Polyfill

1.5.1 · maintenance · verified Sun Apr 19

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.

Common errors

```
ReferenceError: CSS is not defined
```
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).

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.
```
TypeError: CSS.escape is not a function
```
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.

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.
```
SyntaxError: Cannot use import statement outside a module
```
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.

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.

Warnings

gotcha 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.
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.
gotcha 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.
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.
gotcha 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.
Fix: Evaluate whether `cssesc` is a better fit for your project if active development, additional features, or continued maintenance are critical concerns.

Install

npm install css.escape npm
yarn add css.escape yarn
pnpm add css.escape pnpm

Imports

CSS.escape (global in browsers)
wrong:
```
import { escape } from 'css.escape'
```
correct:
```
<script src="css.escape.js"></script>
```
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.
require (for Node.js)
wrong:
```
import 'css.escape';
```
correct:
```
require('css.escape');
```
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.

Quickstart

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.

require('css.escape');

// Verify that CSS.escape is available
if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {
  const escapedId = CSS.escape('.my-class#with spaces!');
  console.log(`Original: .my-class#with spaces!`);
  console.log(`Escaped: ${escapedId}`); // Expected: \.my-class\#with\ spaces\!

  const escapedSelector = `#${CSS.escape('user id')}`;
  console.log(`Selector for 'user id': ${escapedSelector}`); // Expected: #user\ id

  const trickyString = '123_abc-def';
  console.log(`Escaped: ${CSS.escape(trickyString)}`); // Expected: 123_abc-def (no change needed)
} else {
  console.error('CSS.escape is not available after polyfill attempt.');
}

view raw JSON →