# slug

> slugifies even utf-8 chars!

Latest version **12.0.1** (published 2026-07-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install slug
pnpm add slug
yarn add slug
bun add slug
```

Provides the command `slug`.

## Health

**Score 73/100 (B)** — status: active.

Positive: has types package; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 12.0.1 |
| Published | 2026-07-21 |
| First published | 2011-09-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/slug) |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 33 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 414 |
| Author | dodo |
| Maintainers | trott |
| Keywords | slugify, slug, string, utf8, utf-8, unicode, url |

## Links

- npm: https://www.npmjs.com/package/slug
- Repository: https://github.com/Trott/slug
- Issues: https://github.com/Trott/slug/issues
- npm.io page: https://npm.io/package/slug

## Alternatives

- [@mce/gif](https://npm.io/package/@mce/gif.md) — 2.6K weekly downloads
- [cleanse](https://npm.io/package/cleanse.md) — 173 weekly downloads
- [str](https://npm.io/package/str.md) — 127 weekly downloads
- [naming](https://npm.io/package/naming.md) — 95 weekly downloads
- [tap-telco-api](https://npm.io/package/tap-telco-api.md) — 19 weekly downloads

## Recent versions

- 12.0.1 (latest) — 2026-07-21
- 11.0.0-beta.1 (beta) — 2024-10-19
- 12.0.0 — 2026-07-19
- 11.0.1 — 2025-10-13
- 11.0.0 — 2025-05-22
- 10.0.0 — 2024-10-17
- 9.1.0 — 2024-05-24
- 9.0.0 — 2024-03-07
- 8.2.3 — 2023-07-18
- 8.2.2 — 2022-10-02
- 8.2.1 — 2022-10-02
- 8.2.0 — 2022-10-02
- 8.1.0 — 2022-10-02
- 9.0.0-beta.1 — 2022-08-31
- 8.0.0 — 2022-08-31
- … 63 more at https://npm.io/package/slug/versions

## README

# [slug](https://github.com/Trott/slug)

Slugifies strings, even when they contain Unicode.

Make strings URL-safe.

- Respects [RFC 3986](https://tools.ietf.org/html/rfc3986)
- 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

```javascript
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

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

```javascript
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: true,
    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`](https://github.com/simov/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.

---
_Source: https://npm.io/package/slug · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._