css.escape

library1.5.1jsnpmunverified

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.

serialization

npm install css.escape

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CSS.ESCAPE

css.escape

serializationjavascriptv1.5.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CSS.escape (global in browsers)

✓ <script src="css.escape.js"></script>

✗ import { escape } from 'css.escape'

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)

✓ require('css.escape');

✗ import '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.

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.'); }

Debug

Known issues

gotchaThis 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.

affects: >=1.0.0

gotchaThis 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.

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

Errors

Common errors & fixes

ReferenceError: CSS is not defined

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

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

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.

Upgrade

Version history

1.5.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/mathiasbynens/CSS.escape ↗

packagehttps://www.npmjs.com/package/css.escape ↗

homepagehttps://mths.be/cssescape ↗