Unique Names Generator
More than 50,000,000 name combinations out of the box
What is Unique name generator?
Unique name generator is a tree-shakeable Node package for generating random and unique names.
It comes with a list of dictionaries out of the box, but you can also provide your custom ones.
Docs
This documentation is for the unique-names-generator
v4.
If you are using a version 3.x of the library, please refer to the v3 Docs
For the version 1 & 2, please refer to the v2 Docs
Migrating to v4
If you want to migrate, from an older version of the library to v4, please read the Migration guide
Table of contents
- Unique Names Generator
Prerequisites
This project requires NodeJS (at least version 6) and NPM. Node and NPM are really easy to install. To make sure you have them available on your machine, try running the following command.
$ node --version
v7.10.1
$ npm --version
4.2.0
Installation
BEFORE YOU INSTALL: please read the prerequisites
Install the package using npm or Yarn
$ npm i -S unique-names-generator
Or using Yarn
$ yarn add unique-names-generator
Usage
const { uniqueNamesGenerator, adjectives, colors, animals } = require('unique-names-generator');
const randomName = uniqueNamesGenerator({ dictionaries: [adjectives, colors, animals] }); // big_red_donkey
const shortName = uniqueNamesGenerator({
dictionaries: [adjectives, animals, colors], // colors can be omitted here as not used
length: 2
}); // big-donkey
Typescript support
This package export a type definition file so you can use it, out of the box, inside your Typescript project.
import { uniqueNamesGenerator, Config, adjectives, colors, animals } from 'unique-names-generator';
const customConfig: Config = {
dictionaries: [adjectives, colors],
separator: '-',
length: 2,
};
const randomName: string = uniqueNamesGenerator({
dictionaries: [adjectives, colors, animals]
}); // big_red_donkey
const shortName: string = uniqueNamesGenerator(customConfig); // big-donkey
API
uniqueNamesGenerator (options)
Returns a string
with a random generated name
options
Type: Config
dictionaries
Type: array
required: true
This is an array of dictionaries. Each dictionary is an array of strings containing the words to use for generating the string.
The provided dictionaries can be imported from the library as a separate modules and provided in the desired order.
import { uniqueNamesGenerator, adjectives, colors, animals } from 'unique-names-generator';
const shortName: string = uniqueNamesGenerator({
dictionaries: [colors, adjectives, animals]
}); // red_big_donkey
Read more about the dictionaries and how to use them, in the Dictionaries section.
separator
Type: string
required: false
Default: _
A string separator to be used for separate the words generated.
The default separator is set to _
.
length
Type: number
required: false
Default: 3
The default value is set to 3
and it will return a name composed of 3 words.
This values must be equal or minor to the number of dictionaries defined (3 by default).
Setting the length
to a value of 4
will throw an error when only 3 dictionaries are provided.
style
Type: lowerCase | upperCase | capital
required: false
Default: lowerCase
The default value is set to lowerCase
and it will return a lower case name.
By setting the value to upperCase
, the words, will be returned with all the letters in upper case format.
The capital
option will capitalize each word of the unique name generated
import { uniqueNamesGenerator, adjectives, colors, animals } from 'unique-names-generator';
const capitalizedName: string = uniqueNamesGenerator({
dictionaries: [colors, adjectives, animals],
style: 'capital'
}); // Red_Big_Donkey
const upperCaseName: string = uniqueNamesGenerator({
dictionaries: [colors, adjectives, animals],
style: 'upperCase'
}); // RED_BIG_DONKEY
const lowerCaseName: string = uniqueNamesGenerator({
dictionaries: [colors, adjectives, animals],
style: 'lowerCase'
}); // red_big_donkey
seed
Type: number | string
required: false
A seed is used when wanting to deterministically generate a name. As long as the provided seed is the same the generated name will also always be the same.
import { uniqueNamesGenerator, adjectives, colors, animals } from 'unique-names-generator';
const config: Config = {
dictionaries: [adjectives, colors, animals],
separator: '-',
seed: 120498,
};
const nameFromSeed: string = uniqueNamesGenerator(config); // continuous-gray-dragonfly
import { uniqueNamesGenerator, adjectives, colors, animals } from 'unique-names-generator';
const config: Config = {
dictionaries: [adjectives, colors, animals],
separator: '-',
seed: 'you can use strings as a seed',
};
const nameFromSeed: string = uniqueNamesGenerator(config); // stable-crimson-porpoise
Dictionaries available
Numbers
This is a dynamic dictionary. Read more in the Numbers Dictionary section
Adjectives
A list of more than 1,400 adjectives ready for you to use
import { uniqueNamesGenerator, Config, adjectives } from 'unique-names-generator';
const config: Config = {
dictionaries: [adjectives]
}
const characterName: string = uniqueNamesGenerator(config); // big
Animals
A list of more than 350 animals ready to use
import { uniqueNamesGenerator, Config, animals } from 'unique-names-generator';
const config: Config = {
dictionaries: [animals]
}
const characterName: string = uniqueNamesGenerator(config); // donkey
Colors
A list of more than 50 different colors
import { uniqueNamesGenerator, Config, colors } from 'unique-names-generator';
const config: Config = {
dictionaries: [colors]
}
const characterName: string = uniqueNamesGenerator(config); // red
Countries
A list of more than 250 different countries
import { uniqueNamesGenerator, Config, countries } from 'unique-names-generator';
const config: Config = {
dictionaries: [countries]
}
const characterName: string = uniqueNamesGenerator(config); // United Arab Emirates
Names
A list of more than 4,900 unique names
import { uniqueNamesGenerator, Config, names } from 'unique-names-generator';
const config: Config = {
dictionaries: [names]
}
const characterName: string = uniqueNamesGenerator(config); // Winona
Languages
A list of languages
import { uniqueNamesGenerator, Config, languages } from 'unique-names-generator';
const config: Config = {
dictionaries: [languages]
}
const characterName: string = uniqueNamesGenerator(config); // polish
Star Wars
A list of more than 80 unique character names from Star Wars
import { uniqueNamesGenerator, Config, starWars } from 'unique-names-generator';
const config: Config = {
dictionaries: [starWars]
}
const characterName: string = uniqueNamesGenerator(config); // Han Solo
Default dictionaries
By default, the Unique name generator library comes with 3 dictionaries out of the box, so that you can use them straight away. Starting from the version 4 of the library, however, you must explicitly provide the dictionaries within the configuration object. This is for reducing the bundle size and allowing tree shaking to remove the extra dictionaries from your bundle when using custom ones.
The new syntax for using the default dictionaries is the following:
import { uniqueNamesGenerator, Config, adjectives, colors, animals } from 'unique-names-generator';
const config: Config = {
dictionaries: [adjectives, colors, animals]
}
const characterName: string = uniqueNamesGenerator(config); // red_big_donkey
Custom dictionaries
You might want to provide your custom dictionaries to use for generating your unique names, in order to meet your business requirements.
You can easily do that using the dictionaries option.
import { uniqueNamesGenerator } from 'unique-names-generator';
const starWarsCharacters = [
'Han Solo',
'Jabba The Hutt',
'R2-D2',
'Luke Skywalker',
'Princess Leia Organa'
];
const colors = [
'Green', 'Red', 'Yellow', 'Black'
]
const characterName: string = uniqueNamesGenerator({
dictionaries: [colors, starWarsCharacters],
length: 2,
separator: ' '
}); // Green Luke Skywalker
Numbers Dictionary
You can easily generate random numbers inside your unique name using the Numbers dictionary helper.
import { uniqueNamesGenerator, NumberDictionary } from 'unique-names-generator';
const numberDictionary = NumberDictionary.generate({ min: 100, max: 999 });
const characterName: string = uniqueNamesGenerator({
dictionaries: [['Dangerous'], ['Snake'], numberDictionary],
length: 3,
separator: '',
style: 'capital'
}); // DangerousSnake123
Numbers Dictionary API
generate (options)
Returns a string
with a random generated number between 1 and 999
options
Type: Config
min
Type: number
required: false
default: 1
The minimum value to be returned as a random number
max
Type: number
required: false
default: 999
The maximum value to be returned as a random number
length
Type: number
required: false
The length of the random generated number to be returned.
Setting a length of 3 will always return a random number between 100
and 999
. This is the same as setting 100
and 999
as min
and max
option.
Note If set, this will ignore any min
and max
options provided.
Combining custom and provided dictionaries
You can reuse the dictionaries provided by the library. Just import the ones that you need and use them directly in your app.
import { uniqueNamesGenerator, adjectives, colors } from 'unique-names-generator';
const improvedAdjectives = [
...adjectives,
'abrasive',
'brash',
'callous',
'daft',
'eccentric',
];
const xMen = [
'professorX',
'beast',
'colossus',
'cyclops',
'iceman',
'wolverine',
];
const characterName: string = uniqueNamesGenerator({
dictionaries: [improvedAdjectives, color, xMen],
length: 2,
separator: '-'
}); // eccentric-blue-iceman
Migration guide
Migration guide from version 3 to version 4
Unique names generator v4 implement a new breaking change.
dictionaries
config
Mandatory You must now explicitly provide the library with the dictionaries to use. This is for improving flexibility and allowing tree-shaking to remove the unused dictionaries from your bundle size.
Read more about the dictionaries in the Dictionaries section.
v3
import { uniqueNamesGenerator } from 'unique-names-generator';
const randomName = uniqueNamesGenerator(); // big_red_donkey
v4
import { uniqueNamesGenerator, Config, adjectives, colors, animals } from 'unique-names-generator';
const config: Config = {
dictionaries: [adjectives, colors, animals]
}
const randomName = uniqueNamesGenerator(config); // big_red_donkey
Migration guide from version 1 or 2
Unique names generator v3 implements a couple of breaking changes. If are upgrading your library from a version 1 or 2, you might be interested in knowing the following:
uniqueNamesGenerator
This will now work only when a dictionaries
array is provided according to the
v4 breaking change.
v2
import { uniqueNamesGenerator } from 'unique-names-generator';
const randomName = uniqueNamesGenerator();
v4
import { uniqueNamesGenerator, Config, adjectives, colors, animals } from 'unique-names-generator';
const config: Config = {
dictionaries: [adjectives, colors, animals]
}
const randomName = uniqueNamesGenerator(config); // big_red_donkey
Separator
v2
import { uniqueNamesGenerator } from 'unique-names-generator';
const shortName = uniqueNamesGenerator('-'); // big-red-donkey
v4
import { uniqueNamesGenerator, Config, adjectives, colors, animals } from 'unique-names-generator';
const config: Config = {
dictionaries: [adjectives, colors, animals],
separator: '-'
}
const shortName = uniqueNamesGenerator(config); // big-red-donkey
Short
The short
property has been replaced by length
so you can specify as many word as you want
v2
import { uniqueNamesGenerator } from 'unique-names-generator';
const shortName = uniqueNamesGenerator(true); // big-donkey
v4
import { uniqueNamesGenerator, Config, adjectives, colors, animals } from 'unique-names-generator';
const config: Config = {
dictionaries: [adjectives, colors, animals],
length: 2
}
const shortName = uniqueNamesGenerator(config); // big-donkey
Contributing
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
- Fork it!
- Create your feature branch:
git checkout -b my-new-feature
- Add your changes:
git add .
- Commit your changes:
git commit -am 'Add some feature'
- Push to the branch:
git push origin my-new-feature
- Submit a pull request
😎
License
MIT License © Andrea SonnY
✨
Contributors Thanks goes to these wonderful people (emoji key):
Andrea Sonny |
Abhijit Mehta |
Grant Blakeman |
Deepak |
Anurag Jain |
Digibake |
Chase Moskal |
tholst |
Johan Gustafsson |
Alex Wild |
This project follows the all-contributors specification. Contributions of any kind welcome!