Skip to content

Trott/slug

Folders and files

NameName
Last commit message
Last commit date
Oct 17, 2024
Oct 17, 2024
Oct 19, 2024
May 30, 2020
Oct 2, 2022
Oct 17, 2024
Jul 16, 2020
Feb 19, 2014
Feb 3, 2025
Oct 17, 2024
Oct 17, 2024
Feb 17, 2025
Feb 14, 2025
May 24, 2024
Oct 19, 2024

Repository files navigation

Slugifies strings, even when they contain Unicode.

Make strings URL-safe.

  • Respects RFC 3986
  • No dependencies
  • Works in the browser or in Node.js
npm install slug

If you are using TypeScript you can install the accompanying types

npm install --save-dev @types/slug

Example

import slug from 'slug'
var print = console.log.bind(console, '>')

print(slug('i love unicode'))
// > i-love-unicode

print(slug('i love unicode', '_')) // If you prefer something else than `-` as separator
// > i_love_unicode

slug.charmap['♥'] = 'freaking love' // change default charmap or use option {charmap:{…}} as 2. argument
print(slug('I ♥ UNICODE'))
// > i-freaking-love-unicode

// To reset modifications to slug.charmap, use slug.reset():
slug.reset()
print(slug('I ♥ UNICODE'))
// > i-unicode

print(slug('Telephone-Number')) // lower case by default
// > telephone-number

print(slug('Telephone-Number', {lower: false})) // If you want to preserve case
// > Telephone-Number

// We try to provide sensible defaults.
// So Cyrillic text will be transliterated as if it were Russian:
print(slug('маленький подъезд'))
// > malenkij-poduezd

// But maybe you know it's Bulgarian:
print(slug('маленький подъезд', { locale: 'bg' }))
// > malenykiy-podaezd

// To set the default locale:
slug.setLocale('bg')
print(slug('маленький подъезд'))
// > malenykiy-podaezd

print(slug('unicode is ☢'))
// > unicode-is

slug.extend({'☢': 'radioactive'})
print(slug('unicode ♥ is ☢'))
// > unicode-is-radioactive

// slug.extend() modifies the default charmap for the entire process.
// If you need to reset charmap, multicharmap, and the default locale, use slug.reset():

slug.reset()
print(slug('unicode ♥ is ☢'))
// > unicode-is

// Custom removal of characters from resulting slug. Let's say that we want to
// remove all numbers for some reason.
print(slug('one 1 two 2 three 3'))
// > one-1-two-2-three-3
print(slug('one 1 two 2 three 3', { remove: /[0-9]/g }))
// > one-two-three

options

// options is either object or replacement (sets options.replacement)
slug('string', [{options} || 'replacement']);
slug.defaults.mode ='pretty';
slug.defaults.modes['rfc3986'] = {
    replacement: '-',      // replace spaces with replacement
    remove: null,          // (optional) regex to remove characters
    lower: true,           // result in lower case
    charmap: slug.charmap, // replace special characters
    multicharmap: slug.multicharmap, // replace multiple code unit characters
    trim: true,             // trim leading and trailing replacement chars
    fallback: true          // use base64 to generate slug for empty results
};
slug.defaults.modes['pretty'] = {
    replacement: '-',
    remove: null,
    lower: false,
    charmap: slug.charmap,
    multicharmap: slug.multicharmap,
    trim: true,
    fallback: true
};

Differences between slug and slugify packages

Here are some key differences between this package and slugify.

  • Stability: slug is ESM-only.
    slugify supports CommonJS and ESM.
  • Defaults: slug has the lower option enabled by default, lowercasing all slugs ('On SALE' becomes 'on-sale').
    slugify has the lower option disabled by default ('On SALE' becomes 'On-SALE').
  • Symbols: slug removes unrecognized symbols ('$100' becomes '100', '<5' becomes '5', etc.).
    slugify maps them to words ('$100' becomes 'dollar100', '<5' becomes 'less5', etc.).
  • Empty Output: slug will return a short, predictable hash (' ' becomes 'icag' and '🎉' becomes '8joiq').
    slugify will return an empty string (' ' and '🎉' become '').

Playground

A web playground is available at https://trott.github.io/slug/.

There is also a CLI tool available via npx slug. It doesn't allow you to specify options, so it's utility is minimal.