or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

index.mddocs/

cssesc

cssesc is a JavaScript library for escaping CSS strings and identifiers while generating the shortest possible ASCII-only output. It handles Unicode characters, special symbols, and edge cases to produce standards-compliant CSS escape sequences for both string literals and identifiers.

Package Information

  • Package Name: cssesc
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install cssesc

Core Imports

const cssesc = require('cssesc');

For ES modules (with CommonJS interop):

import cssesc from 'cssesc';

In a browser:

<script src="cssesc.js"></script>
<script>
  // cssesc is available as a global variable
  console.log(cssesc('hello world'));
</script>

Basic Usage

const cssesc = require('cssesc');

// Basic string escaping
cssesc('Ich ♥ Bücher');
// → 'Ich \\2665  B\\FC cher'

// Escape for CSS identifier
cssesc('123a2b', { isIdentifier: true });
// → '\\31 23a2b'

// Wrapped in quotes as complete string literal
cssesc('Lorem ipsum "dolor" sit \'amet\'', { 
  quotes: 'single', 
  wrap: true 
});
// → '\'Lorem ipsum "dolor" sit \\\'amet\\\'\''

Capabilities

Main Escape Function

The primary cssesc function that escapes CSS strings and identifiers with configurable options.

/**
 * Escapes CSS strings and identifiers with shortest ASCII-only output
 * @param {string} string - The input string to escape
 * @param {Object} options - Configuration options (optional)
 * @returns {string} The escaped CSS string or identifier
 */
function cssesc(string, options);

Options Object:

interface CssescOptions {
  /** When true, escapes for CSS identifier; when false, escapes for CSS string (default: false) */
  isIdentifier?: boolean;
  /** Quote style for string escaping: 'single' | 'double' (default: 'single') */
  quotes?: 'single' | 'double';
  /** When true, wraps output in quotes as complete CSS string literal (default: false) */
  wrap?: boolean;
  /** When true, escapes all symbols including printable ASCII (default: false) */
  escapeEverything?: boolean;
}

Usage Examples:

// Basic escaping for CSS strings
cssesc('foo © bar ≠ baz 𝌆 qux');
// → 'foo \\A9  bar \\2260  baz \\1D306  qux'

// Escaping for CSS identifiers
cssesc('foo:bar', { isIdentifier: true });
// → 'foo\\:bar'

// Different quote styles
cssesc('Lorem "dolor" sit \'amet\'', { quotes: 'double' });
// → 'Lorem \\"dolor\\" sit \'amet\''

// Complete string literal with wrapping
cssesc('hello world', { wrap: true, quotes: 'double' });
// → '"hello world"'

// Escape everything mode
cssesc('hello', { escapeEverything: true });
// → '\\68\\65\\6C\\6C\\6F'

Global Options Configuration

Global default options object that can be modified to change default behavior.

/**
 * Global default options for cssesc function
 * Can be modified to override defaults globally
 */
cssesc.options = {
  escapeEverything: false,
  isIdentifier: false,
  quotes: 'single',
  wrap: false
};

Usage Example:

// Read current global defaults
console.log(cssesc.options.quotes); // → 'single'

// Override global defaults
cssesc.options.escapeEverything = true;
cssesc.options.quotes = 'double';

// Now all calls use new defaults
cssesc('hello world');
// → '"\\68\\65\\6C\\6C\\6F\\ \\77\\6F\\72\\6C\\64"'

Version Property

Version string property for the library.

/**
 * Semantic version number of the cssesc library
 * @type {string}
 */
cssesc.version; // → '3.0.0'

Command Line Interface

cssesc includes a command-line interface for shell usage.

Installation and Basic Usage

# Install globally
npm install -g cssesc

# Basic usage
cssesc 'föo ♥ bår 𝌆 baz'
# → f\F6o \2665  b\E5r \1D306  baz

CLI Options

# Escape for CSS identifier
cssesc --identifier 'föo ♥ bår'
cssesc -i 'föo ♥ bår'

# Quote style options
cssesc --single-quotes 'hello "world"'  # Default
cssesc -s 'hello "world"'
cssesc --double-quotes 'hello "world"'
cssesc -d 'hello "world"'

# Wrap in quotes
cssesc --wrap 'hello world'
cssesc -w 'hello world'

# Escape everything
cssesc --escape-everything 'hello'
cssesc -e 'hello'

# Version and help
cssesc --version
cssesc -v
cssesc --help
cssesc -h

CLI Usage Examples:

# Standard string escaping
cssesc 'Ich ♥ Bücher'
# → Ich \2665  B\FC cher

# CSS identifier escaping
cssesc --identifier '123abc'
# → \31 23abc

# Double quotes with wrapping
cssesc --double-quotes --wrap 'hello "world"'
# → "hello \"world\""

# Pipe input
echo 'föo ♥ bår' | cssesc
# → f\F6o \2665  b\E5r

Error Handling

The cssesc function gracefully handles various input conditions:

  • Malformed Unicode: Lone surrogate pairs are handled correctly
  • Invalid Options: Invalid quote values fallback to 'single'
  • CLI Errors: Command-line interface provides detailed error messages and stack traces
  • Empty Input: Returns empty string for empty input

Type Definitions

// Main function signature
declare function cssesc(string: string, options?: CssescOptions): string;

// Options interface
interface CssescOptions {
  isIdentifier?: boolean;
  quotes?: 'single' | 'double';
  wrap?: boolean;
  escapeEverything?: boolean;
}

// Static properties
declare namespace cssesc {
  const version: string;
  const options: {
    escapeEverything: boolean;
    isIdentifier: boolean;
    quotes: 'single' | 'double';
    wrap: boolean;
  };
}

export = cssesc;