Unique Names Generator

More than 28,000,000 name combinations

Docs

This documentation is for the unique-names-generator v3. If you are still using an older version of the library, please refer to the v2 Docs

Migrating from v2 to v3

If you want to migrate from al older version into v3, please read the Migration guide

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

Table of contents

• Unique Names Generator
  • Docs
    • Migrating from v2 to v3
  • Prerequisites
  • Table of contents
  • Installation
  • Usage
    • Typescript support
  • API
    • uniqueNamesGenerator(options)
    • options
      • separator
    • length
    • dictionaries
  • Examples
    • Custom dictionaries
    • Combine custom and provided dictionaries
  • Migration guide
    • uniqueNamesGenerator
    • Separator
    • Short
  • Contributing
  • License

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 } = require('unique-names-generator');

const randomName = uniqueNamesGenerator(); // big_red_donkey

const shortName = uniqueNamesGenerator({ 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, UniqueNamesGeneratorConfig } from 'unique-names-generator';

const config: UniqueNamesGeneratorConfig = {
  separator: '-',
  length: 2.
};

const randomName: string = uniqueNamesGenerator(); // big_red_donkey

const shortName: string = uniqueNamesGenerator(config); // big-donkey

API

uniqueNamesGenerator(options)

Returns a string with a random generated name

options

Type: UniqueNamesGeneratorConfig

separator

Type: string

Default: _

A string separator to be used for separate the words generated. The default separator is set to _.

length

Type: number

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)

dictionaries

Type: array

Default: [adjectives, colors, animals]

This is an array of dictionaries. Each dictionary is an array of strings containing the words to use for generating the string.

The default dictionaries are provided in the following order: adjectives, colors and animals. If you don't like them in this order you can still manually import them from the library, then overwrite the dictionaries with your custom order

import { uniqueNamesGenerator, adjectives, colors, animals } from 'unique-names-generator';

const shortName: string = uniqueNamesGenerator({
  dictionaries: [color, adjectives, animal]
}); // red_big_donkey

Examples

Custom dictionaries

By default, the Unique name generator library, come with 3 dictionaries out of the box so that you don't have to provide it manually. However, you might want to extend the provided dictionaries or completely replace with your custom ones 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,
  space: ' '
}); // Green Luke Skywalker

Combine 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, xMen],
  length: 2,
  space: '-'
}); // eccentric-iceman

Migration guide

Unique names generator v3 implements a couple of breaking changes. If are bumping your local version to the v3, you might be interested in knowing the following:

uniqueNamesGenerator

This will still work. Invoking the uniqueNamesGenerator function, will continue work as before :tada:

const { uniqueNamesGenerator } = require('unique-names-generator');

const randomName = uniqueNamesGenerator(); // big_red_donkey

Separator

v2

const shortName = uniqueNamesGenerator('-'); // big-red-donkey

v3

const shortName = uniqueNamesGenerator({ separator: '-' }); // big-red-donkey

Short

The short property has been replaced by length so you can specify as many word as you want

v2

const shortName = uniqueNamesGenerator(true); // big-donkey

v3

const shortName = uniqueNamesGenerator({ length: 2 }); // big-donkey

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Add your changes: git add .
4. Commit your changes: git commit -am 'Add some feature'
5. Push to the branch: git push origin my-new-feature
6. Submit a pull request :sunglasses:

License

MIT License © Andrea SonnY