unique-names-generator

Version 4 introduces a breaking change regarding how dictionaries are handled. In v3, dictionaries were included by default. In v4, you must explicitly provide the dictionaries array in the configuration object to enable tree-shaking and reduce bundle size.

// v3 (Deprecated)
import { uniqueNamesGenerator } from 'unique-names-generator';
const randomName = uniqueNamesGenerator();

// v4 (Current)
import { uniqueNamesGenerator, adjectives, colors, animals } from 'unique-names-generator';
const config = { dictionaries: [adjectives, colors, animals] };
const randomName = uniqueNamesGenerator(config);

Install the package using npm or Yarn. Ensure you have Node.js (version 6+) and NPM installed on your machine.

$ npm i -S unique-names-generator

# or

$ yarn add unique-names-generator

If you are upgrading from version 1 or 2, note the following breaking changes in the current API:

1. Mandatory Dictionaries: uniqueNamesGenerator() now requires a dictionaries array in the config object.
2. Separator: The separator is no longer passed as a direct argument to the function; it must be a key in the configuration object.
3. Length: The short boolean property has been replaced by the length property, which allows you to specify the exact number of words desired.

// v2 (Old)
const shortName = uniqueNamesGenerator('-');
const shortNameBool = uniqueNamesGenerator(true);

// v4 (Current)
const shortName = uniqueNamesGenerator({
  dictionaries: [adjectives, colors],
  separator: '-'
});
const shortNameLen = uniqueNamesGenerator({
  dictionaries: [adjectives, colors],
  length: 2
});

The library provides several pre-defined dictionaries that you can import and use. Starting from version 4, you must explicitly include these in your Config object's dictionaries array to support tree-shaking and smaller bundle sizes.

Available built-in dictionaries include:

• adjectives
• animals
• colors
• countries
• names
• languages
• starWars

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

const config: Config = {
  dictionaries: [adjectives, animals, colors]
};

const characterName: string = uniqueNamesGenerator(config); // e.g., "red_big_donkey"

Import uniqueNamesGenerator and a set of dictionaries (like adjectives, colors, or animals) to generate random names. You can control the name length and the separator used between words.

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],
  length: 2
}); // big-donkey

The package exports type definitions, allowing you to use the Config type for type-safe configuration in your TypeScript projects.

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

You can provide your own arrays of strings as dictionaries to meet specific business requirements. You can also mix custom arrays with the library's built-in dictionaries.

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

// Example 1: Purely custom dictionaries
const starWarsCharacters = ['Han Solo', 'Jabba The Hutt', 'R2-D2'];
const customColors = ['Green', 'Red', 'Yellow'];

const name1 = uniqueNamesGenerator({
  dictionaries: [customColors, starWarsCharacters],
  length: 2,
  separator: ' '
}); // e.g., "Green Han Solo"

// Example 2: Combining built-in and custom
const improvedAdjectives = [...adjectives, 'abrasive', 'brash'];
const xMen = ['professorX', 'wolverine'];

const name2 = uniqueNamesGenerator({
  dictionaries: [improvedAdjectives, colors, xMen],
  length: 2,
  separator: '-'
}); // e.g., "abrasive-blue-wolverine"

The NumberDictionary helper allows you to inject random numbers into your generated names. You can use NumberDictionary.generate() to create a dictionary instance with specific constraints.

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'
}); // e.g., "DangerousSnake123"

The NumberDictionary.generate method accepts a configuration object to define the range and format of the generated numbers.

Options:

• min (number, optional, default: 1): The minimum value to be returned.
• max (number, optional, default: 999): The maximum value to be returned.
• length (number, optional): The fixed length of the random number. Note: If length is set, it ignores min and max. For example, setting length: 3 is equivalent to setting min: 100 and max: 999.

// Example of using length instead of min/max
const numberDictionary = NumberDictionary.generate({ length: 3 });

The primary entry point for the library is the uniqueNamesGenerator function. It is used to generate unique, randomized names based on provided configuration. You can import it directly from the package root.

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

// Example usage (implementation details depend on the generator logic)
const names = uniqueNamesGenerator({ /* options */ });