Skip to content
Slugify a string
JavaScript TypeScript
Branch: master
Clone or download

Latest commit

Latest commit 95ab9e1 May 7, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Create funding.yml May 28, 2019
.editorconfig Init Apr 18, 2018
.gitattributes Meta tweaks Oct 30, 2018
.gitignore Init Apr 18, 2018
.npmrc Init Apr 18, 2018
.travis.yml Require Node.js 10 Jan 21, 2020
index.d.ts Meta tweaks May 7, 2020
index.js Meta tweaks May 7, 2020
index.test-d.ts Meta tweaks May 7, 2020
license Use `@sindresorhus/transliterate` Feb 17, 2020
overridable-replacements.js Add support for Vietnamese Oct 31, 2018
package.json 1.0.0 May 7, 2020
readme.md Add counter for multiple occurences (#46) May 7, 2020
test.js Revert fix to incorrect dashes (#35) (#45) May 7, 2020

readme.md

slugify Build Status

Slugify a string

Useful for URLs, filenames, and IDs.

It handles most major languages, including German (umlauts), Vietnamese, Arabic, Russian, and more.

Install

$ npm install @sindresorhus/slugify

Usage

const slugify = require('@sindresorhus/slugify');

slugify('I ♥ Dogs');
//=> 'i-love-dogs'

slugify('  Déjà Vu!  ');
//=> 'deja-vu'

slugify('fooBar 123 $#%');
//=> 'foo-bar-123'

slugify('я люблю единорогов');
//=> 'ya-lyublyu-edinorogov'

API

slugify(string, options?)

string

Type: string

String to slugify.

options

Type: object

separator

Type: string
Default: '-'

const slugify = require('@sindresorhus/slugify');

slugify('BAR and baz');
//=> 'bar-and-baz'

slugify('BAR and baz', {separator: '_'});
//=> 'bar_and_baz'
lowercase

Type: boolean
Default: true

Make the slug lowercase.

const slugify = require('@sindresorhus/slugify');

slugify('Déjà Vu!');
//=> 'deja-vu'

slugify('Déjà Vu!', {lowercase: false});
//=> 'Deja-Vu'
decamelize

Type: boolean
Default: true

Convert camelcase to separate words. Internally it does fooBarfoo bar.

const slugify = require('@sindresorhus/slugify');

slugify('fooBar');
//=> 'foo-bar'

slugify('fooBar', {decamelize: false});
//=> 'foobar'
customReplacements

Type: Array<string[]>
Default: [ ['&', ' and '], ['🦄', ' unicorn '], ['♥', ' love '] ]

Add your own custom replacements.

The replacements are run on the original string before any other transformations.

This only overrides a default replacement if you set an item with the same key, like &.

const slugify = require('@sindresorhus/slugify');

slugify('Foo@unicorn', {
	customReplacements: [
		['@', 'at']
	]
});
//=> 'fooatunicorn'

Add a leading and trailing space to the replacement to have it separated by dashes:

const slugify = require('@sindresorhus/slugify');

slugify('foo@unicorn', {
	customReplacements: [
		['@', ' at ']
	]
});
//=> 'foo-at-unicorn'

Another example:

const slugify = require('@sindresorhus/slugify');

slugify('I love 🐶', {
	customReplacements: [
		['🐶', 'dogs']
	]
});
//=> 'i-love-dogs'
preserveLeadingUnderscore

Type: boolean
Default: false

If your string starts with an underscore, it will be preserved in the slugified string.

Sometimes leading underscores are intentional, for example, filenames representing hidden paths on a website.

const slugify = require('@sindresorhus/slugify');

slugify('_foo_bar');
//=> 'foo-bar'

slugify('_foo_bar', {preserveLeadingUnderscore: true});
//=> '_foo-bar'

slugify.counter()

Returns a new instance of slugify(string, options?) with a counter to handle multiple occurences of the same string.

Example

const slugify = require('@sindresorhus/slugify');

const countableSlugify = slugify.counter();

countableSlugify('foo bar');
//=> 'foo-bar'

countableSlugify('foo bar');
//=> 'foo-bar-2'

countableSlugify.reset();

countableSlugify('foo bar');
//=> 'foo-bar'

Use-case example of counter

If, for example, you have a document with multiple sections where each subsection has an example.

## Section 1

### Example

## Section 2

### Example

You can then use slugify.counter() to generate unique HTML id's to ensure anchors will link to the right headline.

slugify.reset()

Reset the counter

Example

const slugify = require('@sindresorhus/slugify');

const countableSlugify = slugify.counter();

countableSlugify('foo bar');
//=> 'foo-bar'

countableSlugify('foo bar');
//=> 'foo-bar-2'

countableSlugify.reset();

countableSlugify('foo bar');
//=> 'foo-bar'

Related

  • slugify-cli - CLI for this module
  • transliterate - Convert Unicode characters to Latin characters using transliteration
  • filenamify - Convert a string to a valid safe filename
You can’t perform that action at this time.