slugify
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');
slugify(' Déjà Vu! ');
slugify('fooBar 123 $#%');
slugify('я люблю единорогов');
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');
slugify('BAR and baz', {separator: '_'});
slugify('BAR and baz', {separator: ''});
lowercase
Type: boolean
Default: true
Make the slug lowercase.
const slugify = require('@sindresorhus/slugify');
slugify('Déjà Vu!');
slugify('Déjà Vu!', {lowercase: false});
decamelize
Type: boolean
Default: true
Convert camelcase to separate words. Internally it does fooBar
→ foo bar
.
const slugify = require('@sindresorhus/slugify');
slugify('fooBar');
slugify('fooBar', {decamelize: false});
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']
]
});
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 ']
]
});
Another example:
const slugify = require('@sindresorhus/slugify');
slugify('I love 🐶', {
customReplacements: [
['🐶', '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');
slugify('_foo_bar', {preserveLeadingUnderscore: true});
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');
countableSlugify('foo bar');
countableSlugify.reset();
countableSlugify('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');
countableSlugify('foo bar');
countableSlugify.reset();
countableSlugify('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