# url-slug

> Tiny, zero-dependency slug generator (~700 bytes gzipped) with full TypeScript support — converts strings into clean, RFC 3986-compliant slugs and reverts them back to sentences

Latest version **5.1.0** (published 2026-08-06) · MIT license · 0 weekly downloads

## Install

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

## Health

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

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.1.0 |
| Published | 2026-08-06 |
| First published | 2015-09-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=14.0.0 |
| Dependencies | 0 |
| Unpacked size | 25.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 91 |
| Author | stldo |
| Maintainers | stldo |
| Keywords | convert, revert, rfc-3986, seo, slug, slugify, string, url, url-safe, url-slug, urlify |

## Links

- npm: https://www.npmjs.com/package/url-slug
- Repository: https://github.com/stldo/url-slug
- Homepage: https://github.com/stldo/url-slug#readme
- Issues: https://github.com/stldo/url-slug/issues
- npm.io page: https://npm.io/package/url-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

- 5.1.0 (latest) — 2026-08-06
- 3.0.0-beta.3 (beta) — 2020-07-26
- 5.0.1 — 2026-06-19
- 5.0.0 — 2026-03-06
- 4.0.1 — 2023-06-18
- 4.0.0 — 2023-06-18
- 3.0.6 — 2023-06-17
- 3.0.5 — 2023-06-17
- 3.0.4 — 2022-05-16
- 3.0.3 — 2022-01-29
- 3.0.2 — 2021-05-13
- 3.0.1 — 2021-01-06
- 3.0.0 — 2021-01-04
- 2.3.2 — 2020-07-26
- 3.0.0-beta.2 — 2020-07-26
- … 14 more at https://npm.io/package/url-slug/versions

## README

# url-slug [![License][1]][license] [![Build status][2]][3] [![npm][4]][6] [![npm][5]][6] [![minzipped size][7]][8]

- **Zero dependencies** for a minimal bundle footprint
- **Ultra-lightweight**, weighing in at **~700 bytes** minified and gzipped
- **TypeScript-ready** with built-in type definitions
- **ES6-compatible** for use in all modern environments
- **SEO-friendly**, generating clean, readable URL slugs
- **RFC 3986-compliant** by default
- Customize slug generation with **custom replacements**
- Easily **revert slugs** back into regular sentences

## Installation

```bash
npm install url-slug
```

## Usage

```javascript
import urlSlug from "url-slug";

urlSlug("Sir James Paul McCartney MBE is an English singer-songwriter");
// sir-james-paul-mc-cartney-mbe-is-an-english-singer-songwriter
```

### convert(value[, options])

Returns the `value` converted to a slug.

#### value

The string to be slugified.

#### options

|Name|Description|Default|
|---|---|---|
|`camelCase`|Split on camel case occurrences|`true`|
|`dictionary`|[Characters to be replaced](#dictionary-option)|`{}`|
|`separator`|[Character or string](#separator-characters) used to separate the slug fragments|`"-"`|
|`transformer`|A built-in transformer or a custom function (`null` to leave the string unchanged)|`LOWERCASE_TRANSFORMER`|

#### Examples

```javascript
import {
  TITLECASE_TRANSFORMER,
  UPPERCASE_TRANSFORMER,
  convert,
} from "url-slug";

convert("Comfortably Numb", {
  transformer: UPPERCASE_TRANSFORMER,
});
// COMFORTABLY-NUMB

convert("á é í ó ú Á É Í Ó Ú ç Ç ª º ¹ ² ½ ¼", {
  separator: "_",
  transformer: false,
});
// a_e_i_o_u_A_E_I_O_U_c_C_a_o_1_2_1_2_1_4

convert("Red, red wine, stay close to me…", {
  separator: "",
  transformer: TITLECASE_TRANSFORMER,
});
// RedRedWineStayCloseToMe

convert("Schwarzweiß", {
  dictionary: { ß: "ss", z: "z " },
});
// schwarz-weiss
```

### revert(value[, options])

Returns the `value` converted back into a regular sentence.

#### value

The slug to be reverted to a sentence.

#### options

|Name|Description|Default|
|---|---|---|
|`camelCase`|Split on camel case occurrences|`false`|
|`separator`|[Character or string](#separator-characters) used to split the slug (`null` for automatic splitting)|`null`|
|`transformer`|A built-in transformer or a custom function (`null` to leave the string unchanged)|`false`|

#### Examples

```javascript
import { TITLECASE_TRANSFORMER, revert } from "url-slug";

revert("Replace-every_separator.allowed~andSplitCamelCaseToo", {
  camelCase: true,
});
// Replace every separator allowed and Split Camel Case Too

revert("this-slug-needs-a-title_case", {
  separator: "-",
  transformer: TITLECASE_TRANSFORMER,
});
// This Slug Needs A Title_case
```

### Custom transformers

A custom transformer is a function that receives two arguments: `fragments`,
an array containing the words of a sentence or slug, and `separator`, the
separator string set in the `convert()` options. When `revert()` calls a
transformer, the `separator` argument is always a space character (`" "`) —
the `separator` option is used only to split the slug. Transformers must
always return a string.

#### Examples

```javascript
import { convert, revert } from "url-slug";

convert("O’Neill is an American surfboard, surfwear and equipment brand", {
  transformer: (fragments) => fragments.join("x").toUpperCase(),
});
// OxNEILLxISxANxAMERICANxSURFBOARDxSURFWEARxANDxEQUIPMENTxBRAND

revert("WEIrd_SNAke_CAse", {
  separator: "_",
  transformer: (fragments, separator) =>
    fragments
      .map(
        (fragment) =>
          fragment.slice(0, -2).toLowerCase() + fragment.slice(-2).toUpperCase()
      )
      .join(separator),
});
// weiRD snaKE caSE
```

### Built-in transformers

#### LOWERCASE_TRANSFORMER

Converts the result to lowercase. E.g.: `// SOME WORDS >> some words`

#### SENTENCECASE_TRANSFORMER

Converts the result to sentence case. E.g.: `// sOME WORDS >> Some words`

#### UPPERCASE_TRANSFORMER

Converts the result to uppercase. E.g.: `// some words >> SOME WORDS`

#### TITLECASE_TRANSFORMER

Converts the result to title case. E.g.: `// sOME wORDS >> Some Words`

### Separator characters

Any character, or an empty string, can be used as the `separator`. When the
`separator` is an empty string, `revert()` will split the slug only on camel
case occurrences if the `camelCase` option is set to `true`; otherwise, it
returns the string unchanged. The following characters are valid according to
RFC 3986 — defined as _unreserved_ or _sub-delims_ — and are used by
`revert()` when automatic splitting is enabled, i.e. when `separator` is set
to `null`:

`-`, `.`, `_`, `~`, `^`, `-`, `.`, `_`, `~`, `!`, `$`, `&`, `'`, `(`, `)`, `*`,
`+`, `,`, `;` or `=`

### `dictionary` option

This option must be an object whose keys are single characters and whose
values are strings of any length:

```js
import { convert } from "url-slug";

convert("♥øß", {
  dictionary: {
    "♥": "love",
    ø: "o",
    ß: "ss",
    //...
  },
});
// loveoss
```

To add separators before or after a specific character, include a space
before or after the replacement value in the dictionary:

```js
import { convert } from "url-slug";

convert("♥øß", {
  dictionary: {
    "♥": "love",
    ø: " o", // A space was added before
    ß: "ss",
    //...
  },
});
// love-oss

convert("♥øß", {
  dictionary: {
    "♥": "love",
    ø: " o ", // A space was added before and after
    ß: "ss",
    //...
  },
});
// love-o-ss

convert("♥øß", {
  dictionary: {
    "♥": "love",
    ø: "o ", // A space was added after
    ß: "ss",
    //...
  },
});
// loveo-ss
```

### Compatibility

Compatible with any environment that supports ES6.

## License

[The MIT License][license]

Copyright (C) 2015-present stldo

[1]: https://img.shields.io/github/license/stldo/url-slug
[2]: https://img.shields.io/github/actions/workflow/status/stldo/url-slug/validate.yml?branch=master
[3]: https://github.com/stldo/url-slug/actions/workflows/validate.js.yml
[4]: https://img.shields.io/npm/dm/url-slug
[5]: https://img.shields.io/npm/v/url-slug
[6]: https://www.npmjs.com/package/url-slug
[7]: https://img.shields.io/bundlejs/size/url-slug
[8]: https://bundlejs.com/?q=url-slug
[license]: ./LICENSE

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