Package Exports

unique-names-generator

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (unique-names-generator) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Unique Names Generator

More than 28,000,000 name combinations

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 Otherwise, for versions 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

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

Unique Names Generator

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, colors, animals],
  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, animals],
  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 default adjectives, colors and animals 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 in the Examples 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)

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: 'capital'
}); // RED_BIG_DONKEY

const lowerCaseName: string = uniqueNamesGenerator({
  dictionaries: [colors, adjectives, animals],
  style: 'capital'
}); // red_big_donkey

Examples

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

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.

Mandatory `dictionaries` config

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 Examples section.

import { uniqueNamesGenerator } from 'unique-names-generator';

const randomName = uniqueNamesGenerator(); // big_red_donkey

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.

import { uniqueNamesGenerator } from 'unique-names-generator';

const randomName = uniqueNamesGenerator();

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

import { uniqueNamesGenerator } from 'unique-names-generator';

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

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

import { uniqueNamesGenerator } from 'unique-names-generator';

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

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