0
# Unique Names Generator
1

2
Unique Names Generator is a tree-shakeable TypeScript library that generates unique and memorable names by combining words from various built-in dictionaries. It provides flexible configuration options including custom separators, text styling, deterministic seeding, and custom dictionaries, offering over 50 million default name combinations.
3

4
## Package Information
5

6
- **Package Name**: unique-names-generator
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install unique-names-generator`
10

11
## Core Imports
12

13
```typescript
14
import { uniqueNamesGenerator, Config, adjectives, colors, animals, NumberDictionary } from "unique-names-generator";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { uniqueNamesGenerator, Config, adjectives, colors, animals, NumberDictionary } = require("unique-names-generator");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { uniqueNamesGenerator, adjectives, colors, animals } from "unique-names-generator";
27

28
// Generate a random name using built-in dictionaries
29
const randomName = uniqueNamesGenerator({ 
30
  dictionaries: [adjectives, colors, animals] 
31
}); // "big_red_donkey"
32

33
// Custom configuration
34
const customName = uniqueNamesGenerator({
35
  dictionaries: [adjectives, animals],
36
  separator: '-',
37
  length: 2,
38
  style: 'capital'
39
}); // "Big-Donkey"
40

41
// With deterministic seeding
42
const seededName = uniqueNamesGenerator({
43
  dictionaries: [adjectives, colors, animals],
44
  seed: 12345
45
}); // Always produces the same result with this seed
46
```
47

48
## Capabilities
49

50
### Name Generation
51

52
Core function for generating unique names from dictionary combinations.
53

54
```typescript { .api }
55
/**
56
 * Generates a unique name based on provided configuration
57
 * @param config - Configuration object defining dictionaries and options
58
 * @returns Generated unique name string
59
 * @throws Error if no dictionaries provided or invalid configuration
60
 */
61
function uniqueNamesGenerator(config: Config): string;
62

63
interface Config {
64
  /** Array of word arrays to use for generation (required) */
65
  dictionaries: string[][];
66
  /** String to separate words (default: "_") */
67
  separator?: string;
68
  /** Number of words to generate (default: length of dictionaries array) */
69
  length?: number;
70
  /** Text formatting style (default: none - no transformation applied) */
71
  style?: 'lowerCase' | 'upperCase' | 'capital';
72
  /** Deterministic seed for consistent generation */
73
  seed?: number | string;
74
}
75
```
76

77
**Configuration Options:**
78

79
- **dictionaries** (required): Array of string arrays. Each sub-array contains words for that position
80
- **separator**: Custom separator between words (default: "_"). Can be any string, emoji, or word
81
- **length**: Number of words to include (must be ≤ number of dictionaries provided)
82
- **style**: Text formatting - 'lowerCase', 'upperCase', 'capital', or none (default: undefined, no transformation)
83
- **seed**: Number or string for deterministic generation
84

85
**Usage Examples:**
86

87
```typescript
88
// Multiple separators
89
const hyphenated = uniqueNamesGenerator({
90
  dictionaries: [adjectives, animals],
91
  separator: '-'
92
}); // "clever-fox"
93

94
const spaced = uniqueNamesGenerator({
95
  dictionaries: [colors, animals],
96
  separator: ' '
97
}); // "blue elephant"
98

99
// Different styles  
100
const lowercase = uniqueNamesGenerator({
101
  dictionaries: [adjectives, colors],
102
  style: 'lowerCase'
103
}); // "bright_green"
104

105
const uppercase = uniqueNamesGenerator({
106
  dictionaries: [adjectives, colors], 
107
  style: 'upperCase'
108
}); // "BRIGHT_GREEN"
109

110
const capitalized = uniqueNamesGenerator({
111
  dictionaries: [adjectives, colors],
112
  style: 'capital'
113
}); // "Bright_Green"
114

115
// Custom dictionaries
116
const starWarsColors = [
117
  ['Dangerous', 'Mysterious', 'Ancient'],
118
  ['Jedi', 'Sith', 'Droid'], 
119
  ['Master', 'Knight', 'Padawan']
120
];
121

122
const customName = uniqueNamesGenerator({
123
  dictionaries: starWarsColors,
124
  separator: ' ',
125
  length: 2
126
}); // "Dangerous Jedi"
127
```
128

129
### Dynamic Number Generation
130

131
Utility class for generating random numbers as dictionary entries.
132

133
```typescript { .api }
134
class NumberDictionary {
135
  /**
136
   * Generates a string array containing a single random number
137
   * @param config - Configuration for number generation
138
   * @returns Array with single number string
139
   */
140
  static generate(config?: Partial<NumberConfig>): string[];
141
}
142

143
interface NumberConfig {
144
  /** Minimum number value (default: 1) */
145
  min: number;
146
  /** Maximum number value (default: 999) */
147
  max: number;
148
  /** Number of digits (overrides min/max if provided) */
149
  length?: number;
150
}
151
```
152

153
**Usage Examples:**
154

155
```typescript
156
import { uniqueNamesGenerator, NumberDictionary, adjectives, animals } from "unique-names-generator";
157

158
// Generate numbers in range
159
const numberDict = NumberDictionary.generate({ min: 100, max: 999 });
160
const nameWithNumber = uniqueNamesGenerator({
161
  dictionaries: [adjectives, animals, numberDict],
162
  separator: ''
163
}); // "cleverfox847"
164

165
// Generate numbers by length
166
const threeDigits = NumberDictionary.generate({ length: 3 });
167
const codeName = uniqueNamesGenerator({
168
  dictionaries: [['Agent'], threeDigits],
169
  separator: '-'
170
}); // "Agent-247"
171

172
// Default range (1-999)
173
const defaultNumbers = NumberDictionary.generate();
174
const simpleName = uniqueNamesGenerator({
175
  dictionaries: [animals, defaultNumbers]
176
}); // "elephant_42"
177
```
178

179
### Built-in Dictionaries
180

181
Pre-built word collections for immediate use.
182

183
```typescript { .api }
184
/** Array of 1400+ adjectives */
185
const adjectives: string[];
186

187
/** Array of 350+ animal names */
188
const animals: string[];
189

190
/** Array of 50+ color names */
191
const colors: string[];
192

193
/** Array of 250+ country names */
194
const countries: string[];
195

196
/** Array of 4900+ personal names */
197
const names: string[];
198

199
/** Array of language names */
200
const languages: string[];
201

202
/** Array of 80+ Star Wars character names */
203
const starWars: string[];
204
```
205

206
**Usage Examples:**
207

208
```typescript
209
// Single dictionary
210
const animalName = uniqueNamesGenerator({
211
  dictionaries: [animals]
212
}); // "elephant"
213

214
// Multiple built-in dictionaries
215
const countryName = uniqueNamesGenerator({
216
  dictionaries: [adjectives, countries],
217
  separator: ' '
218
}); // "beautiful France"
219

220
const characterName = uniqueNamesGenerator({
221
  dictionaries: [colors, starWars],
222
  separator: ' ',
223
  length: 2
224
}); // "blue Luke Skywalker"
225

226
// Mixing built-in and custom
227
const customAdjectives = [...adjectives, 'stellar', 'cosmic', 'quantum'];
228
const mixedName = uniqueNamesGenerator({
229
  dictionaries: [customAdjectives, colors, animals]
230
}); // "stellar_purple_tiger"
231
```
232

233
## Error Handling
234

235
The library throws descriptive errors for invalid configurations:
236

237
```typescript
238
// Missing dictionaries
239
uniqueNamesGenerator({}); 
240
// Throws: 'A "dictionaries" array must be provided...'
241

242
// Invalid length
243
uniqueNamesGenerator({
244
  dictionaries: [animals, colors],
245
  length: 5
246
}); 
247
// Throws: 'The length cannot be bigger than the number of dictionaries...'
248

249
// Invalid length value
250
uniqueNamesGenerator({
251
  dictionaries: [animals],
252
  length: 0
253
}); 
254
// Throws: 'Invalid length provided'
255
```
256

257
## Advanced Usage Patterns
258

259
### Deterministic Generation
260

261
Use seeds for reproducible results across sessions:
262

263
```typescript
264
const config = {
265
  dictionaries: [adjectives, colors, animals],
266
  seed: 'my-app-user-123'
267
};
268

269
const name1 = uniqueNamesGenerator(config); // "continuous_gray_dragonfly" 
270
const name2 = uniqueNamesGenerator(config); // "continuous_gray_dragonfly" (same result)
271

272
// Numeric seeds work too
273
const numericSeed = uniqueNamesGenerator({
274
  dictionaries: [colors, animals],
275
  seed: 42
276
}); // Always produces the same result
277
```
278

279
### Complex Dictionary Combinations
280

281
Combine built-in dictionaries with custom ones:
282

283
```typescript
284
// Extend existing dictionaries
285
const enhancedAdjectives = [
286
  ...adjectives,
287
  'magnificent', 'extraordinary', 'phenomenal'
288
];
289

290
const teamNames = [
291
  'Team', 'Squad', 'Crew', 'Guild', 'Alliance'
292
];
293

294
const projectName = uniqueNamesGenerator({
295
  dictionaries: [teamNames, enhancedAdjectives, colors],
296
  separator: ' ',
297
  style: 'capital'
298
}); // "Team Magnificent Blue"
299
```
300

301
### Multiple Configurations
302

303
Generate different name styles for different purposes:
304

305
```typescript
306
const baseConfig = {
307
  dictionaries: [adjectives, animals],
308
  seed: 'consistent-seed'
309
};
310

311
// Username style
312
const username = uniqueNamesGenerator({
313
  ...baseConfig,
314
  separator: '_',
315
  style: 'lowerCase'
316
}); // "clever_fox"
317

318
// Display name style  
319
const displayName = uniqueNamesGenerator({
320
  ...baseConfig,
321
  separator: ' ',
322
  style: 'capital'
323
}); // "Clever Fox"
324

325
// Code name style
326
const codeName = uniqueNamesGenerator({
327
  ...baseConfig,
328
  separator: '-',
329
  style: 'upperCase'
330
}); // "CLEVER-FOX"
331
```