slugify

Slugifies a String

weekly downloads8.1M

versionv1.6.6

licenseMIT

categoryutility

slugifyslugurlurlify

Overview

The slugify package transforms arbitrary strings into clean, URL-safe slugs by transliterating Unicode characters, replacing spaces with separators, and stripping unwanted symbols. With over 8 million weekly downloads, it's become the de facto standard for generating human-readable URLs, file names, and identifiers in Node.js applications.

Unlike simple regex-based approaches, slugify maintains a comprehensive character mapping (charmap.json) that correctly transliterates thousands of Unicode characters—converting 'ñ' to 'n', '♥' to 'love', and '☢' to 'radioactive'. This makes it suitable for internationalized applications where user-generated content may contain characters from dozens of writing systems.

The library provides fine-grained control through options like strict mode (strips all non-alphanumeric except separators), locale-specific rules, custom replacement characters, and regex-based character removal. It's synchronous, has zero dependencies, and works in both Node.js and browser environments.

Despite being updated 3 years ago at version 1.6.6, the package remains stable and widely deployed in production systems. Its maturity and comprehensive Unicode handling make it reliable for applications that need predictable slug generation without maintaining custom transliteration logic.

Quick Start

typescript

import slugify from 'slugify';

// Basic usage with common options
const title = 'Node.js: Building Modern APIs';
const slug = slugify(title, {
  lower: true,
  strict: true,
  remove: /[*+~.()'\";:@]/g
});
console.log(slug); // 'nodejs-building-modern-apis'

// Handling Unicode with locale support
const vietnamese = 'Đà Nẵng';
const vnSlug = slugify(vietnamese, { locale: 'vi', lower: true });
console.log(vnSlug); // 'da-nang'

// Custom separator for file names
const fileName = 'User Profile Picture.jpg';
const safeFile = slugify(fileName, {
  replacement: '_',
  lower: true,
  strict: false
});
console.log(safeFile); // 'user_profile_picture.jpg'

// Extending character map for custom transliterations
slugify.extend({ '☃': 'snowman', '★': 'star' });
const custom = slugify('Rate us ★★★☃', { lower: true });
console.log(custom); // 'rate-us-starstarstarsnowman'

// Strict mode removes everything except alphanumeric and replacement
const messy = 'Hello... World!!! (2024)';
const clean = slugify(messy, { lower: true, strict: true });
console.log(clean); // 'hello-world-2024'

Use Cases

Blog and CMS URL generation: Convert article titles like 'Top 10 JavaScript Frameworks in 2024!' into clean URLs like 'top-10-javascript-frameworks-in-2024', preserving readability while ensuring valid routing paths.

File system operations: Sanitize user-uploaded file names containing spaces, special characters, or Unicode to prevent file system errors—turning 'Résumé (Final Version).pdf' into 'resume-final-version.pdf'.

Database identifiers: Generate human-readable unique keys for database records where URLs or slugs serve as primary identifiers, such as e-commerce product SKUs or wiki page slugs that need to remain consistent across updates.

Internationalization scenarios: Handle content in multiple languages by leveraging locale-specific transliteration—Vietnamese 'Đồng' becomes 'dong' with locale: 'vi', while German 'ü' becomes 'ue' with locale: 'de'.

API endpoint normalization: Create consistent, lowercase endpoint names from user-defined resource names in auto-generated REST APIs or GraphQL schemas, ensuring predictable routing without manual slug maintenance.

Pros & Cons

Pros

+Comprehensive Unicode transliteration with 2000+ character mappings covering most major writing systems
+Highly configurable with locale support, custom separators, strict mode, regex removal, and extendable character maps
+Zero runtime dependencies and small footprint, suitable for both server and client-side use
+Predictable behavior with well-documented options and extensive real-world testing across millions of installations

Cons

−No updates in 3+ years (last published 2021), raising concerns about maintenance for edge cases or security issues
−Global state for character map extensions requires cache clearing when dynamically modifying mappings in long-running processes
−Synchronous-only API may block event loop when processing very large strings in high-throughput scenarios

Comparisons

slugify vs change-case

utility

Install

bash

npm install slugify

bash

pnpm add slugify

bash

bun add slugify

Overview

Quick Start

typescript

import slugify from 'slugify';

// Basic usage with common options
const title = 'Node.js: Building Modern APIs';
const slug = slugify(title, {
  lower: true,
  strict: true,
  remove: /[*+~.()'\";:@]/g
});
console.log(slug); // 'nodejs-building-modern-apis'

// Handling Unicode with locale support
const vietnamese = 'Đà Nẵng';
const vnSlug = slugify(vietnamese, { locale: 'vi', lower: true });
console.log(vnSlug); // 'da-nang'

// Custom separator for file names
const fileName = 'User Profile Picture.jpg';
const safeFile = slugify(fileName, {
  replacement: '_',
  lower: true,
  strict: false
});
console.log(safeFile); // 'user_profile_picture.jpg'

// Extending character map for custom transliterations
slugify.extend({ '☃': 'snowman', '★': 'star' });
const custom = slugify('Rate us ★★★☃', { lower: true });
console.log(custom); // 'rate-us-starstarstarsnowman'

// Strict mode removes everything except alphanumeric and replacement
const messy = 'Hello... World!!! (2024)';
const clean = slugify(messy, { lower: true, strict: true });
console.log(clean); // 'hello-world-2024'

Use Cases

Pros & Cons

Pros

+Comprehensive Unicode transliteration with 2000+ character mappings covering most major writing systems
+Highly configurable with locale support, custom separators, strict mode, regex removal, and extendable character maps
+Zero runtime dependencies and small footprint, suitable for both server and client-side use
+Predictable behavior with well-documented options and extensive real-world testing across millions of installations

Cons

−No updates in 3+ years (last published 2021), raising concerns about maintenance for edge cases or security issues
−Global state for character map extensions requires cache clearing when dynamically modifying mappings in long-running processes
−Synchronous-only API may block event loop when processing very large strings in high-throughput scenarios