slug

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

1import slug from 'slug'
2var print = console.log.bind(console, '>')
3
4print(slug('i love unicode'))
5// > i-love-unicode
6
7print(slug('i love unicode', '_')) // If you prefer something else than `-` as separator
8// > i_love_unicode
9
10slug.charmap['♥'] = 'freaking love' // change default charmap or use option {charmap:{…}} as 2. argument
11print(slug('I ♥ UNICODE'))
12// > i-freaking-love-unicode
13
14// To reset modifications to slug.charmap, use slug.reset():
15slug.reset()
16print(slug('I ♥ UNICODE'))
17// > i-unicode
18
19print(slug('Telephone-Number')) // lower case by default
20// > telephone-number
21
22print(slug('Telephone-Number', {lower: false})) // If you want to preserve case
23// > Telephone-Number
24
25// We try to provide sensible defaults.
26// So Cyrillic text will be transliterated as if it were Russian:
27print(slug('маленький подъезд'))
28// > malenkij-poduezd
29
30// But maybe you know it's Bulgarian:
31print(slug('маленький подъезд', { locale: 'bg' }))
32// > malenykiy-podaezd
33
34// To set the default locale:
35slug.setLocale('bg')
36print(slug('маленький подъезд'))
37// > malenykiy-podaezd
38
39print(slug('unicode is ☢'))
40// > unicode-is
41
42slug.extend({'☢': 'radioactive'})
43print(slug('unicode ♥ is ☢'))
44// > unicode-is-radioactive
45
46// slug.extend() modifies the default charmap for the entire process.
47// If you need to reset charmap, multicharmap, and the default locale, use slug.reset():
48
49slug.reset()
50print(slug('unicode ♥ is ☢'))
51// > unicode-is
52
53// Custom removal of characters from resulting slug. Let's say that we want to
54// remove all numbers for some reason.
55print(slug('one 1 two 2 three 3'))
56// > one-1-two-2-three-3
57print(slug('one 1 two 2 three 3', { remove: /[0-9]/g }))
58// > one-two-three

options

1// options is either object or replacement (sets options.replacement)
2slug('string', [{options} || 'replacement']);

1slug.defaults.mode ='pretty';
2slug.defaults.modes['rfc3986'] = {
3    replacement: '-',      // replace spaces with replacement
4    remove: null,          // (optional) regex to remove characters
5    lower: true,           // result in lower case
6    charmap: slug.charmap, // replace special characters
7    multicharmap: slug.multicharmap, // replace multiple code unit characters
8    trim: true,             // trim leading and trailing replacement chars
9    fallback: true          // use base64 to generate slug for empty results
10};
11slug.defaults.modes['pretty'] = {
12    replacement: '-',
13    remove: null,
14    lower: false,
15    charmap: slug.charmap,
16    multicharmap: slug.multicharmap,
17    trim: true,
18    fallback: true
19};

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.