or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-css-escape

A robust polyfill for the CSS.escape utility method as defined in CSSOM

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/css.escape@1.5.x

To install, run

npx @tessl/cli install tessl/npm-css-escape@1.5.0

index.mddocs/

CSS.escape

CSS.escape is a robust polyfill for the CSS.escape utility method as defined in the CSSOM specification. It provides safe escaping of CSS identifiers and selectors by handling special characters, Unicode code points, and edge cases according to the official CSS specification.

Package Information

  • Package Name: css.escape
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install css.escape

Core Imports

require('css.escape');
// CSS.escape is now available globally

For case-insensitive systems:

require('CSS.escape');

Browser usage:

<script src="css.escape.js"></script>
<!-- CSS.escape is now available globally -->

Basic Usage

require('css.escape');

// Escape CSS identifiers safely
const selector = CSS.escape('my-element#id');
console.log(selector); // "my-element\\#id"

// Use in CSS selectors
const elementId = 'user-123';
const element = document.querySelector('#' + CSS.escape(elementId));

// Handle special characters
const className = 'my class!@#';
const escaped = CSS.escape(className);
console.log(escaped); // "my\\ class\\!\\@\\#"

Capabilities

CSS Identifier Escaping

Escapes a CSS identifier according to the CSSOM specification, handling all special characters and Unicode code points.

/**
 * Escapes a CSS identifier according to CSSOM specification
 * @param {any} value - The value to be escaped as a CSS identifier (will be converted to string)
 * @returns {string} The escaped CSS identifier string
 * @throws {TypeError} If no arguments are provided
 */
CSS.escape(value);

Parameter Details:

  • value (any, required): The value to escape. Will be converted to string using String(value). Common types include strings, numbers, booleans, null, and undefined.

Return Value:

  • Returns a string with the escaped CSS identifier

Error Handling:

  • Throws TypeError with message "CSS.escape requires an argument." when called with no arguments

Escaping Rules:

The function follows the CSSOM specification for escaping CSS identifiers:

  • NULL character (U+0000): Replaced with replacement character (U+FFFD)
  • Control characters (U+0001-U+001F, U+007F): Escaped as hex sequences (\1 , \2 , etc.)
  • Leading digits (0-9): Escaped as hex sequences when at start of identifier
  • Leading hyphen + digit: Digit escaped as hex sequence when following initial hyphen
  • Single hyphen: Escaped as \- when it's the only character
  • Valid identifier characters: Letters (a-zA-Z), digits (0-9), hyphen (-), underscore (_), and Unicode characters ≥ U+0080 are preserved
  • Other special characters: Escaped with backslash (\!, \@, \#, etc.)

Usage Examples:

// Basic escaping
CSS.escape('hello-world'); // "hello-world" (no escaping needed)
CSS.escape('hello world'); // "hello\\ world" (space escaped)
CSS.escape('123abc'); // "\\31 23abc" (leading digit escaped)

// Special characters
CSS.escape('my#id'); // "my\\#id"
CSS.escape('class.name'); // "class\\.name"
CSS.escape('item[0]'); // "item\\[0\\]"

// Edge cases
CSS.escape(''); // "" (empty string)
CSS.escape('-'); // "\\-" (single hyphen)
CSS.escape('-9abc'); // "-\\39 abc" (hyphen + digit)

// Type conversion
CSS.escape(123); // "123" (converted to string first, then leading digits escaped)
CSS.escape(true); // "true"
CSS.escape(null); // "null"
CSS.escape(undefined); // "undefined"

// Unicode handling
CSS.escape('café'); // "café" (Unicode preserved)
CSS.escape('\x00'); // "\uFFFD" (NULL replaced)
CSS.escape('\x01'); // "\\1 " (control character escaped)

Implementation Details

Polyfill Behavior

The library automatically detects existing native CSS.escape implementations:

  • If CSS.escape already exists natively, it returns the native implementation
  • Otherwise, it provides the polyfill implementation
  • Creates global CSS object if it doesn't exist
  • Supports UMD pattern for browser, CommonJS, and AMD environments

Module Exports

CommonJS (Node.js):

const cssEscape = require('css.escape');
// Returns the CSS.escape function directly

AMD:

define(['css.escape'], function(cssEscape) {
    // cssEscape is the CSS.escape function
});

Browser Global:

<script src="css.escape.js"></script>
<script>
    // CSS.escape is available globally
    const escaped = CSS.escape('my-id');
</script>

Function Properties

CSS.escape.length; // 1 (indicates one required parameter)