or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-sindresorhus--slugify

Slugify a string with comprehensive Unicode transliteration and extensive customization options

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@sindresorhus/slugify@2.2.x

To install, run

npx @tessl/cli install tessl/npm-sindresorhus--slugify@2.2.0

index.mddocs/

Slugify

Slugify provides comprehensive string-to-slug conversion with Unicode transliteration, extensive customization options, and multi-language support. It transforms any string into URL-safe, filename-safe, and ID-safe representations by converting Unicode characters to ASCII equivalents.

Package Information

  • Package Name: @sindresorhus/slugify
  • Package Type: npm
  • Language: JavaScript (ES modules with TypeScript definitions)
  • Installation: npm install @sindresorhus/slugify

Core Imports

import slugify from '@sindresorhus/slugify';
import { slugifyWithCounter } from '@sindresorhus/slugify';

For CommonJS:

const slugify = require('@sindresorhus/slugify');
const { slugifyWithCounter } = require('@sindresorhus/slugify');

Basic Usage

import slugify from '@sindresorhus/slugify';

// Basic slugification
slugify('I ♥ Dogs');
//=> 'i-love-dogs'

slugify('  Déjà Vu!  ');
//=> 'deja-vu'

slugify('fooBar 123 $#%');
//=> 'foo-bar-123'

// Multi-language support
slugify('я люблю единорогов');
//=> 'ya-lyublyu-edinorogov'

// With options
slugify('BAR and baz', { separator: '_', lowercase: false });
//=> 'BAR_and_baz'

Architecture

The package is built around two core functions:

  • Main slugify function: Converts individual strings with comprehensive customization options
  • Counter-based slugify: Generates unique sequential slugs for handling duplicates
  • Transliteration engine: Converts Unicode characters to ASCII using @sindresorhus/transliterate
  • Built-in replacements: Common symbol and emoji mappings that can be overridden

Capabilities

String Slugification

Converts any string into a URL-safe, filename-safe slug with comprehensive Unicode transliteration and customization options.

/**
 * Slugify a string
 * @param string - String to slugify
 * @param options - Configuration options
 * @returns Slugified string
 */
function slugify(string: string, options?: Options): string;

interface Options {
  /** Character(s) to use as separator. @default '-' */
  readonly separator?: string;
  /** Make the slug lowercase. @default true */
  readonly lowercase?: boolean;
  /** Convert camelcase to separate words. @default true */
  readonly decamelize?: boolean;
  /** Custom character replacements. @default [['&', ' and '], ['🦄', ' unicorn '], ['♥', ' love ']] */
  readonly customReplacements?: ReadonlyArray<[string, string]>;
  /** Preserve leading underscore. @default false */
  readonly preserveLeadingUnderscore?: boolean;
  /** Preserve trailing dash. @default false */
  readonly preserveTrailingDash?: boolean;
  /** Characters to preserve in the output. @default [] */
  readonly preserveCharacters?: string[];
}

Usage Examples:

import slugify from '@sindresorhus/slugify';

// Custom separator
slugify('BAR and baz', { separator: '_' });
//=> 'bar_and_baz'

slugify('BAR and baz', { separator: '' });
//=> 'barandbaz'

// Case handling
slugify('Déjà Vu!', { lowercase: false });
//=> 'Deja-Vu'

// Decamelization
slugify('fooBar', { decamelize: false });
//=> 'foobar'

// Custom replacements
slugify('Foo@unicorn', {
  customReplacements: [['@', ' at ']]
});
//=> 'foo-at-unicorn'

// Character preservation
slugify('foo_bar#baz', { preserveCharacters: ['#'] });
//=> 'foo-bar#baz'

// Leading underscore preservation
slugify('_foo_bar', { preserveLeadingUnderscore: true });
//=> '_foo-bar'

// Trailing dash preservation
slugify('foo-bar-', { preserveTrailingDash: true });
//=> 'foo-bar-'

Counter-Based Slugification

Creates a slugify function with counter functionality to handle multiple occurrences of the same string by appending sequential numbers.

/**
 * Returns a new instance of slugify with a counter to handle duplicates
 * @returns CountableSlugify function with reset method
 */
function slugifyWithCounter(): CountableSlugify;

interface CountableSlugify {
  /** Reset the counter to start over */
  reset: () => void;
  /** Slugify function with counter for handling duplicates */
  (string: string, options?: Options): string;
}

Usage Examples:

import { slugifyWithCounter } from '@sindresorhus/slugify';

const slugify = slugifyWithCounter();

slugify('foo bar');
//=> 'foo-bar'

slugify('foo bar');
//=> 'foo-bar-2'

slugify('foo bar');
//=> 'foo-bar-3'

// Reset counter
slugify.reset();

slugify('foo bar');
//=> 'foo-bar'

// Use case: generating unique HTML IDs
const sections = ['Example', 'Example', 'Introduction', 'Example'];
const ids = sections.map(title => slugify(title));
//=> ['example', 'example-2', 'introduction', 'example-3']

Built-in Character Replacements

The package includes built-in character replacements that can be overridden via customReplacements:

const builtinReplacements = [
  ['&', ' and '],
  ['🦄', ' unicorn '],
  ['♥', ' love ']
];

Error Handling

The functions throw errors in the following cases:

  • TypeError: When the input string is not a string type
  • Error: When the separator character is included in preserveCharacters array
// Throws TypeError
slugify(123);
//=> TypeError: Expected a string, got `number`

// Throws Error  
slugify('test', { 
  separator: '-', 
  preserveCharacters: ['-'] 
});
//=> Error: The separator character `-` cannot be included in preserved characters