0
# Slugify
1

2
Slugify provides comprehensive string-to-slug conversion with Unicode transliteration, extensive customization options, and multi-language support. It transforms any string into URL-safe, filename-safe, and ID-safe representations by converting Unicode characters to ASCII equivalents.
3

4
## Package Information
5

6
- **Package Name**: @sindresorhus/slugify  
7
- **Package Type**: npm
8
- **Language**: JavaScript (ES modules with TypeScript definitions)
9
- **Installation**: `npm install @sindresorhus/slugify`
10

11
## Core Imports
12

13
```javascript
14
import slugify from '@sindresorhus/slugify';
15
import { slugifyWithCounter } from '@sindresorhus/slugify';
16
```
17

18
For CommonJS:
19

20
```javascript
21
const slugify = require('@sindresorhus/slugify');
22
const { slugifyWithCounter } = require('@sindresorhus/slugify');
23
```
24

25
## Basic Usage
26

27
```javascript
28
import slugify from '@sindresorhus/slugify';
29

30
// Basic slugification
31
slugify('I ♥ Dogs');
32
//=> 'i-love-dogs'
33

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

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

40
// Multi-language support
41
slugify('я люблю единорогов');
42
//=> 'ya-lyublyu-edinorogov'
43

44
// With options
45
slugify('BAR and baz', { separator: '_', lowercase: false });
46
//=> 'BAR_and_baz'
47
```
48

49
## Architecture
50

51
The package is built around two core functions:
52

53
- **Main slugify function**: Converts individual strings with comprehensive customization options
54
- **Counter-based slugify**: Generates unique sequential slugs for handling duplicates
55
- **Transliteration engine**: Converts Unicode characters to ASCII using `@sindresorhus/transliterate`
56
- **Built-in replacements**: Common symbol and emoji mappings that can be overridden
57

58
## Capabilities
59

60
### String Slugification
61

62
Converts any string into a URL-safe, filename-safe slug with comprehensive Unicode transliteration and customization options.
63

64
```javascript { .api }
65
/**
66
 * Slugify a string
67
 * @param string - String to slugify
68
 * @param options - Configuration options
69
 * @returns Slugified string
70
 */
71
function slugify(string: string, options?: Options): string;
72

73
interface Options {
74
  /** Character(s) to use as separator. @default '-' */
75
  readonly separator?: string;
76
  /** Make the slug lowercase. @default true */
77
  readonly lowercase?: boolean;
78
  /** Convert camelcase to separate words. @default true */
79
  readonly decamelize?: boolean;
80
  /** Custom character replacements. @default [['&', ' and '], ['🦄', ' unicorn '], ['♥', ' love ']] */
81
  readonly customReplacements?: ReadonlyArray<[string, string]>;
82
  /** Preserve leading underscore. @default false */
83
  readonly preserveLeadingUnderscore?: boolean;
84
  /** Preserve trailing dash. @default false */
85
  readonly preserveTrailingDash?: boolean;
86
  /** Characters to preserve in the output. @default [] */
87
  readonly preserveCharacters?: string[];
88
}
89
```
90

91
**Usage Examples:**
92

93
```javascript
94
import slugify from '@sindresorhus/slugify';
95

96
// Custom separator
97
slugify('BAR and baz', { separator: '_' });
98
//=> 'bar_and_baz'
99

100
slugify('BAR and baz', { separator: '' });
101
//=> 'barandbaz'
102

103
// Case handling
104
slugify('Déjà Vu!', { lowercase: false });
105
//=> 'Deja-Vu'
106

107
// Decamelization
108
slugify('fooBar', { decamelize: false });
109
//=> 'foobar'
110

111
// Custom replacements
112
slugify('Foo@unicorn', {
113
  customReplacements: [['@', ' at ']]
114
});
115
//=> 'foo-at-unicorn'
116

117
// Character preservation
118
slugify('foo_bar#baz', { preserveCharacters: ['#'] });
119
//=> 'foo-bar#baz'
120

121
// Leading underscore preservation
122
slugify('_foo_bar', { preserveLeadingUnderscore: true });
123
//=> '_foo-bar'
124

125
// Trailing dash preservation
126
slugify('foo-bar-', { preserveTrailingDash: true });
127
//=> 'foo-bar-'
128
```
129

130
### Counter-Based Slugification
131

132
Creates a slugify function with counter functionality to handle multiple occurrences of the same string by appending sequential numbers.
133

134
```javascript { .api }
135
/**
136
 * Returns a new instance of slugify with a counter to handle duplicates
137
 * @returns CountableSlugify function with reset method
138
 */
139
function slugifyWithCounter(): CountableSlugify;
140

141
interface CountableSlugify {
142
  /** Reset the counter to start over */
143
  reset: () => void;
144
  /** Slugify function with counter for handling duplicates */
145
  (string: string, options?: Options): string;
146
}
147
```
148

149
**Usage Examples:**
150

151
```javascript
152
import { slugifyWithCounter } from '@sindresorhus/slugify';
153

154
const slugify = slugifyWithCounter();
155

156
slugify('foo bar');
157
//=> 'foo-bar'
158

159
slugify('foo bar');
160
//=> 'foo-bar-2'
161

162
slugify('foo bar');
163
//=> 'foo-bar-3'
164

165
// Reset counter
166
slugify.reset();
167

168
slugify('foo bar');
169
//=> 'foo-bar'
170

171
// Use case: generating unique HTML IDs
172
const sections = ['Example', 'Example', 'Introduction', 'Example'];
173
const ids = sections.map(title => slugify(title));
174
//=> ['example', 'example-2', 'introduction', 'example-3']
175
```
176

177
## Built-in Character Replacements
178

179
The package includes built-in character replacements that can be overridden via `customReplacements`:
180

181
```javascript { .api }
182
const builtinReplacements = [
183
  ['&', ' and '],
184
  ['🦄', ' unicorn '],
185
  ['♥', ' love ']
186
];
187
```
188

189
## Error Handling
190

191
The functions throw errors in the following cases:
192

193
- `TypeError`: When the input string is not a string type
194
- `Error`: When the separator character is included in `preserveCharacters` array
195

196
```javascript
197
// Throws TypeError
198
slugify(123);
199
//=> TypeError: Expected a string, got `number`
200

201
// Throws Error  
202
slugify('test', { 
203
  separator: '-', 
204
  preserveCharacters: ['-'] 
205
});
206
//=> Error: The separator character `-` cannot be included in preserved characters
207
```