cssesc

library3.0.0jsnpmunverified

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.

http-networking web-framework

npm install cssesc

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CSSESC

cssesc

http-networkingjavascriptv3.0.0

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.

cssesc

✓ import cssesc from 'cssesc';

✗ import { cssesc } from 'cssesc';

The library primarily exposes a default function, not named exports, for ESM environments.

cssesc

✓ const cssesc = require('cssesc');

This is the standard CommonJS import pattern, as shown in the package's documentation.

Options

✓ import cssesc, { Options } from 'cssesc';

✗ type Options = { isIdentifier?: boolean; quotes?: 'single' | 'double'; wrap?: boolean; }; // Manual definition

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.

Demonstrates basic CSS string and identifier escaping using `cssesc` with various options for quote types and wrapping, including handling of non-ASCII characters.

import cssesc from 'cssesc'; console.log('--- Escaping for CSS String Literal ---'); const unsafeString = 'Hello, world! I ♥ JavaScript and "quotes".'; const escapedString = cssesc(unsafeString); console.log(`Original: "${unsafeString}"\nEscaped: '${escapedString}'`); // Expected: 'Hello, world! I \2665 JavaScript and \"quotes\".' console.log('\n--- Escaping for CSS Identifier ---'); const unsafeIdentifier = '1a-b.c d'; const escapedIdentifier = cssesc(unsafeIdentifier, { isIdentifier: true }); console.log(`Original: "${unsafeIdentifier}"\nEscaped: '${escapedIdentifier}'`); // Expected: '\31 a-b\.c\ d' console.log('\n--- Escaping with Double Quotes and Wrapping ---'); const anotherUnsafeString = 'My ID is #foo/bar and it has \'single\' quotes.'; const wrappedDoubleQuoteEscaped = cssesc(anotherUnsafeString, { quotes: 'double', wrap: true }); console.log(`Original: "${anotherUnsafeString}"\nEscaped: ${wrappedDoubleQuoteEscaped}`); // Expected: "My ID is #foo/bar and it has 'single' quotes." console.log('\n--- Escaping a non-ASCII character (emojis) ---'); const emojiString = 'User😊Name'; const escapedEmoji = cssesc(emojiString, { isIdentifier: true }); console.log(`Original: "${emojiString}"\nEscaped: '${escapedEmoji}'`); // Expected: 'User\1F60A Name'

Debug

Known issues

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

fix

Always pass `{ isIdentifier: true }` in the options object when escaping a value intended for a CSS identifier. For example: `cssesc('123abc', { isIdentifier: true })`.

affects: >=0.1.0

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

fix

For ESM modules, use `import cssesc from 'cssesc';`. Avoid `import { cssesc } from 'cssesc';` or attempting to `require` in an ESM context.

affects: >=1.0.0

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

fix

Ensure your project uses a actively maintained Node.js LTS version (e.g., Node.js 18 or 20) for optimal security and performance.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: cssesc is not a function

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

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(...)`.

Error: Module 'cssesc' does not provide an export named 'cssesc'

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.

fix

Change your import statement to `import cssesc from 'cssesc';` to correctly import the default exported function.

CSS selector for ID or class with special characters doesn't work

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

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.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/mathiasbynens/cssesc ↗

packagehttps://www.npmjs.com/package/cssesc ↗

homepagehttps://mths.be/cssesc ↗