or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-slugify

Converts strings into URL-friendly slugs by transliterating Unicode characters and removing special characters

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/slugify@1.6.x

To install, run

npx @tessl/cli install tessl/npm-slugify@1.6.0

Slugify

Slugify converts strings into URL-friendly slugs by transliterating Unicode characters to their English equivalents, removing special characters, and formatting text with customizable separators. It provides comprehensive character mapping support for international text and offers extensive configuration options for precise slug generation.

Package Information

Package Name: slugify
Package Type: npm
Language: JavaScript (with TypeScript definitions)
Installation: npm install slugify

Core Imports

const slugify = require('slugify');

For TypeScript/ES modules:

import slugify from 'slugify';

Browser (global):

// Available as window.slugify
const slug = slugify('some text');

Basic Usage

const slugify = require('slugify');

// Basic slugification
slugify('Hello World!'); // 'Hello-World!'

// With replacement character
slugify('Hello World!', '_'); // 'Hello_World!'

// With options
slugify('Hello World!', {
  replacement: '-',  // replace spaces with replacement character
  remove: undefined, // remove characters that match regex
  lower: false,      // convert to lower case
  strict: false,     // strip special characters except replacement
  locale: 'vi',      // language code of the locale to use
  trim: true         // trim leading and trailing replacement chars
}); // 'Hello-World!'

// Extend with custom character mappings
slugify.extend({'☢': 'radioactive'});
slugify('unicode ♥ is ☢'); // 'unicode-love-is-radioactive'

Capabilities

String Slugification

Converts input strings into URL-friendly slugs with comprehensive Unicode support.

/**
 * Converts a string into a URL-friendly slug
 * @param string - The input string to slugify
 * @param options - Configuration options or replacement character
 * @returns URL-friendly slug string
 * @throws Error with message "slugify: string argument expected" if first argument is not a string
 */
function slugify(
  string: string,
  options?:
    | {
        replacement?: string;
        remove?: RegExp;
        lower?: boolean;
        strict?: boolean;
        locale?: string;
        trim?: boolean;
      }
    | string
): string;

Usage Examples:

// Basic conversion
slugify('Some String'); // 'Some-String'

// Custom replacement
slugify('foo bar baz', '_'); // 'foo_bar_baz'

// Lowercase conversion
slugify('Foo bAr baZ', {lower: true}); // 'foo-bar-baz'

// Remove specific characters
slugify('foo *+~.() bar \'"!:@ baz', {
  remove: /[$*_+~.()'"!\-:@]/g
}); // 'foo-bar-baz'

// Strict mode (only alphanumeric + replacement)
slugify('foo_bar. -@-baz!', {strict: true}); // 'foobar-baz'

// Locale-specific transliteration
slugify('Ich ♥ Deutsch', {locale: 'de'}); // 'Ich-liebe-Deutsch'

// Preserve leading/trailing replacement chars
slugify(' foo bar baz ', {trim: false}); // '-foo-bar-baz-'

// Empty replacement
slugify('foo bar baz', {replacement: ''}); // 'foobarbaz'

Character Map Extension

Extends or overrides the default character mapping with custom transliterations.

/**
 * Extends the global character map with custom character mappings
 * @param customMap - Key-value pairs where keys are characters to replace and values are their replacements
 * @returns void
 * @note Modifies the global charMap for the entire process
 */
slugify.extend(customMap: { [key: string]: any }): void;

Usage Examples:

// Add custom character mappings
slugify.extend({'☢': 'radioactive', '♪': 'music'});
slugify('unicode ♥ is ☢ and ♪'); // 'unicode-love-is-radioactive-and-music'

// Override existing mappings
slugify.extend({'+': '-'});
slugify('day + night'); // 'day-night'

// Handle empty string mappings
slugify.extend({'ъ': ''});
slugify('ъяъ'); // 'ya'

// Reset character map (clear module cache)
delete require.cache[require.resolve('slugify')];
const slugify = require('slugify');

Options

SlugifyOptions Interface

interface SlugifyOptions {
  /** Character to replace spaces with (default: '-') */
  replacement?: string;
  
  /** Regular expression to remove characters (default: undefined) */
  remove?: RegExp;
  
  /** Convert to lowercase (default: false) */
  lower?: boolean;
  
  /** Strip special characters except replacement (default: false) */
  strict?: boolean;
  
  /** Language code for locale-specific transliteration (default: undefined) */
  locale?: string;
  
  /** Trim leading and trailing replacement chars (default: true) */
  trim?: boolean;
}

Supported Locales

The package supports locale-specific character mappings for enhanced transliteration:

bg (Bulgarian): Specialized Cyrillic character handling
de (German): Umlaut conversion (ä→ae, ö→oe, ü→ue, ß→ss) and German symbols
es (Spanish): Spanish-specific symbols and currency representations
fr (French): French symbols and currency representations
pt (Portuguese): Portuguese symbols and currency representations
uk (Ukrainian): Ukrainian Cyrillic character variations
vi (Vietnamese): Vietnamese character handling (Đ→D, đ→d)
da (Danish): Danish-specific characters (Ø→OE, Å→AA)
nb (Norwegian Bokmål): Norwegian character mappings
it (Italian): Italian conjunction handling
nl (Dutch): Dutch conjunction handling
sv (Swedish): Swedish character mappings

Character Support

Built-in Character Mappings

Slugify includes comprehensive Unicode character support:

Latin Characters: À, Á, Â, Ã, Ä, Å, Æ, Ç, È, É, etc.
Greek Characters: α, β, γ, δ, ε, ζ, η, θ, ι, κ, λ, μ, etc.
Cyrillic Characters: а, б, в, г, д, е, ё, ж, з, и, й, к, etc.
Arabic Characters: ء, آ, أ, ؤ, إ, ئ, ا, ب, ة, ت, ث, ج, etc.
Currency Symbols: €, $, £, ¥, ₿, ₺, etc.
Mathematical Symbols: ∑, ∞, ∂, ∆, etc.

Special Character Handling

Unicode Normalization: Applies .normalize() to handle combining characters
Default Allowed Characters: $*_+~.()'"!:@- (preserved unless removed via options)
Whitespace Consolidation: Multiple consecutive spaces treated as single space
Replacement Character Consolidation: Prevents duplicate replacement characters

Error Handling

The package provides clear error messaging for invalid input:

try {
  slugify(undefined);
} catch (err) {
  console.log(err.message); // "slugify: string argument expected"
}

Environment Compatibility

Node.js: Full CommonJS support
Browser: Available as window.slugify global
AMD: Compatible with RequireJS and similar loaders
ES Modules: Default export with TypeScript definitions
Dependencies: Zero dependencies for maximum compatibility