0
# Slugify
1

2
Slugify converts strings into URL-friendly slugs by transliterating Unicode characters to their English equivalents, removing special characters, and formatting text with customizable separators. It provides comprehensive character mapping support for international text and offers extensive configuration options for precise slug generation.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const slugify = require('slugify');
15
```
16

17
For TypeScript/ES modules:
18

19
```typescript
20
import slugify from 'slugify';
21
```
22

23
Browser (global):
24

25
```javascript
26
// Available as window.slugify
27
const slug = slugify('some text');
28
```
29

30
## Basic Usage
31

32
```javascript
33
const slugify = require('slugify');
34

35
// Basic slugification
36
slugify('Hello World!'); // 'Hello-World!'
37

38
// With replacement character
39
slugify('Hello World!', '_'); // 'Hello_World!'
40

41
// With options
42
slugify('Hello World!', {
43
  replacement: '-',  // replace spaces with replacement character
44
  remove: undefined, // remove characters that match regex
45
  lower: false,      // convert to lower case
46
  strict: false,     // strip special characters except replacement
47
  locale: 'vi',      // language code of the locale to use
48
  trim: true         // trim leading and trailing replacement chars
49
}); // 'Hello-World!'
50

51
// Extend with custom character mappings
52
slugify.extend({'☢': 'radioactive'});
53
slugify('unicode ♥ is ☢'); // 'unicode-love-is-radioactive'
54
```
55

56
## Capabilities
57

58
### String Slugification
59

60
Converts input strings into URL-friendly slugs with comprehensive Unicode support.
61

62
```typescript { .api }
63
/**
64
 * Converts a string into a URL-friendly slug
65
 * @param string - The input string to slugify
66
 * @param options - Configuration options or replacement character
67
 * @returns URL-friendly slug string
68
 * @throws Error with message "slugify: string argument expected" if first argument is not a string
69
 */
70
function slugify(
71
  string: string,
72
  options?:
73
    | {
74
        replacement?: string;
75
        remove?: RegExp;
76
        lower?: boolean;
77
        strict?: boolean;
78
        locale?: string;
79
        trim?: boolean;
80
      }
81
    | string
82
): string;
83
```
84

85
**Usage Examples:**
86

87
```javascript
88
// Basic conversion
89
slugify('Some String'); // 'Some-String'
90

91
// Custom replacement
92
slugify('foo bar baz', '_'); // 'foo_bar_baz'
93

94
// Lowercase conversion
95
slugify('Foo bAr baZ', {lower: true}); // 'foo-bar-baz'
96

97
// Remove specific characters
98
slugify('foo *+~.() bar \'"!:@ baz', {
99
  remove: /[$*_+~.()'"!\-:@]/g
100
}); // 'foo-bar-baz'
101

102
// Strict mode (only alphanumeric + replacement)
103
slugify('foo_bar. -@-baz!', {strict: true}); // 'foobar-baz'
104

105
// Locale-specific transliteration
106
slugify('Ich ♥ Deutsch', {locale: 'de'}); // 'Ich-liebe-Deutsch'
107

108
// Preserve leading/trailing replacement chars
109
slugify(' foo bar baz ', {trim: false}); // '-foo-bar-baz-'
110

111
// Empty replacement
112
slugify('foo bar baz', {replacement: ''}); // 'foobarbaz'
113
```
114

115
### Character Map Extension
116

117
Extends or overrides the default character mapping with custom transliterations.
118

119
```typescript { .api }
120
/**
121
 * Extends the global character map with custom character mappings
122
 * @param customMap - Key-value pairs where keys are characters to replace and values are their replacements
123
 * @returns void
124
 * @note Modifies the global charMap for the entire process
125
 */
126
slugify.extend(customMap: { [key: string]: any }): void;
127
```
128

129
**Usage Examples:**
130

131
```javascript
132
// Add custom character mappings
133
slugify.extend({'☢': 'radioactive', '♪': 'music'});
134
slugify('unicode ♥ is ☢ and ♪'); // 'unicode-love-is-radioactive-and-music'
135

136
// Override existing mappings
137
slugify.extend({'+': '-'});
138
slugify('day + night'); // 'day-night'
139

140
// Handle empty string mappings
141
slugify.extend({'ъ': ''});
142
slugify('ъяъ'); // 'ya'
143

144
// Reset character map (clear module cache)
145
delete require.cache[require.resolve('slugify')];
146
const slugify = require('slugify');
147
```
148

149
## Options
150

151
### SlugifyOptions Interface
152

153
```typescript { .api }
154
interface SlugifyOptions {
155
  /** Character to replace spaces with (default: '-') */
156
  replacement?: string;
157
  
158
  /** Regular expression to remove characters (default: undefined) */
159
  remove?: RegExp;
160
  
161
  /** Convert to lowercase (default: false) */
162
  lower?: boolean;
163
  
164
  /** Strip special characters except replacement (default: false) */
165
  strict?: boolean;
166
  
167
  /** Language code for locale-specific transliteration (default: undefined) */
168
  locale?: string;
169
  
170
  /** Trim leading and trailing replacement chars (default: true) */
171
  trim?: boolean;
172
}
173
```
174

175
### Supported Locales
176

177
The package supports locale-specific character mappings for enhanced transliteration:
178

179
- `bg` (Bulgarian): Specialized Cyrillic character handling
180
- `de` (German): Umlaut conversion (ä→ae, ö→oe, ü→ue, ß→ss) and German symbols
181
- `es` (Spanish): Spanish-specific symbols and currency representations
182
- `fr` (French): French symbols and currency representations  
183
- `pt` (Portuguese): Portuguese symbols and currency representations
184
- `uk` (Ukrainian): Ukrainian Cyrillic character variations
185
- `vi` (Vietnamese): Vietnamese character handling (Đ→D, đ→d)
186
- `da` (Danish): Danish-specific characters (Ø→OE, Å→AA)
187
- `nb` (Norwegian Bokmål): Norwegian character mappings
188
- `it` (Italian): Italian conjunction handling
189
- `nl` (Dutch): Dutch conjunction handling
190
- `sv` (Swedish): Swedish character mappings
191

192
## Character Support
193

194
### Built-in Character Mappings
195

196
Slugify includes comprehensive Unicode character support:
197

198
- **Latin Characters**: À, Á, Â, Ã, Ä, Å, Æ, Ç, È, É, etc.
199
- **Greek Characters**: α, β, γ, δ, ε, ζ, η, θ, ι, κ, λ, μ, etc.
200
- **Cyrillic Characters**: а, б, в, г, д, е, ё, ж, з, и, й, к, etc.
201
- **Arabic Characters**: ء, آ, أ, ؤ, إ, ئ, ا, ب, ة, ت, ث, ج, etc.
202
- **Currency Symbols**: €, $, £, ¥, ₿, ₺, etc.
203
- **Mathematical Symbols**: ∑, ∞, ∂, ∆, etc.
204
- **Special Symbols**: ©, ®, ™, ♥, etc.
205

206
### Special Character Handling
207

208
- **Unicode Normalization**: Applies `.normalize()` to handle combining characters
209
- **Default Allowed Characters**: `$*_+~.()'"!:@-` (preserved unless removed via options)
210
- **Whitespace Consolidation**: Multiple consecutive spaces treated as single space
211
- **Replacement Character Consolidation**: Prevents duplicate replacement characters
212

213
## Error Handling
214

215
The package provides clear error messaging for invalid input:
216

217
```javascript
218
try {
219
  slugify(undefined);
220
} catch (err) {
221
  console.log(err.message); // "slugify: string argument expected"
222
}
223
```
224

225
## Environment Compatibility
226

227
- **Node.js**: Full CommonJS support
228
- **Browser**: Available as `window.slugify` global
229
- **AMD**: Compatible with RequireJS and similar loaders
230
- **ES Modules**: Default export with TypeScript definitions
231
- **Dependencies**: Zero dependencies for maximum compatibility