random-words-slugs

A lightweight, fast, and feature-rich random word slug generator.

brave-golden-fox          ← default (kebab, 3 words)
BraveGoldenFox            ← pascal format
brave_golden_fox-42       ← with number
🦊 brave-golden-fox       ← with emoji
apple-ant-art             ← alliteration

Features

• 🪶 Tiny — zero dependencies, < 5 KB minzipped
• ⚡ Fast — pure in-memory, no I/O
• 🎨 8 formats — kebab, snake, camel, pascal, title, upper, dot, path
• 🔐 Secure & Seeded — deterministic PRNG seeds or cryptographically secure WebCrypto randoms
• 🎭 Themes & Alliteration — scoped noun themes and forced alliteration configurations!
• 🔢 Number suffix — e.g. swift-fox-247
• 😎 Emoji support — prepend or append from curated sets
• 📝 4 word types — adjectives, nouns, verbs, adverbs
• ✏️ Custom word lists — bring your own words
• 📏 maxLength — trim slug to fit a character limit
• 🔵 TypeScript — full types included

Install

npm install random-words-slugs
# or
yarn add random-words-slugs
# or
pnpm add random-words-slugs

Quick Start

import generateSlug from "random-words-slugs";

generateSlug();
// "brave-golden-fox"

generateSlug(2);
// "tiny-wolf"

API

generateSlug(wordCount?, options?)

Generates a single random slug. You can pass the properties directly via an options object, or supply a wordCount digit as the first parameter!

generateSlug()
// "brave-golden-fox"

generateSlug(4)
// "calm-wild-golden-fox"

generateSlug({ format: "camel", wordCount: 2 })
// "tinyWolf"

generateSlug(3, { alliteration: true })
// "fierce-fast-falcon"

Options

| Option | Type | Default | Description | |-----------------|-----------------------|--------------------------------|------------------------------------------------------| | wordCount | number | 3 | Number of words (or pass as first param directly) | | seed | string \| number | — | Deterministic PRNG seed for identical output | | secure | boolean | false | Uses Node/Web crypto.getRandomValues() | | alliteration | boolean | false | Forces all words to start with the same letter | | theme | WordTheme | "all" | Picks nouns matching scoped themes (e.g., "food") | | partsOfSpeech | WordCategory[] | ["adjective","adjective","noun"] | Order of word categories | | format | SlugFormat | "kebab" | Output format (see below) | | separator | string | — | Custom separator (overrides format separator) | | appendNumber | boolean | false | Append a random number 0–999 | | appendEmoji | boolean | false | Append a random emoji | | prependEmoji | boolean | false | Prepend a random emoji | | emojiCategory | EmojiCategory | "all" | Emoji set: "animals", "nature", "objects", "smileys", "all" | | customWords | Partial<Record<WordCategory, string[]>> | — | Replace built-in word lists | | maxLength | number | — | Trim slug to this many characters (emoji excluded) |

Themes & Alliteration

// Force all words to target the same starting letter
generateSlug(3, { alliteration: true });
// "swift-silent-shark"

// Confine generated nouns to a specific theme!
// Themes: "food" | "places" | "professions" | "tech" | "nature" | "animals" | "objects"
generateSlug(2, { theme: "food" });
// "sweet-pizza"

Secure & Deterministic Randoms

// Using a seed explicitly generates identically predictable output every single time!
generateSlug(3, { seed: "user-123" });
// "brave-copper-wallaby"
generateSlug(3, { seed: "user-123" });
// "brave-copper-wallaby"

// Using WebCrypto/Crypto globally secures random logic safely
generateSlug(3, { secure: true });
// "holographic-quantum-pulse"

Formats

generateSlug({ format: "kebab"  })  // "brave-golden-fox"   ← default
generateSlug({ format: "snake"  })  // "brave_golden_fox"
generateSlug({ format: "camel"  })  // "braveGoldenFox"
generateSlug({ format: "pascal" })  // "BraveGoldenFox"
generateSlug({ format: "title"  })  // "Brave Golden Fox"
generateSlug({ format: "upper"  })  // "BRAVE-GOLDEN-FOX"
generateSlug({ format: "dot"    })  // "brave.golden.fox"
generateSlug({ format: "path"   })  // "brave/golden/fox"

Numbers & Emoji

generateSlug({ appendNumber: true })
// "swift-cyan-wolf-384"

generateSlug({ appendEmoji: true })
// "swift-cyan-wolf 🐺"

generateSlug({ prependEmoji: true, emojiCategory: "animals" })
// "🦊 swift-cyan-wolf"

generateSlug({ appendEmoji: true, appendNumber: true })
// "swift-cyan-wolf-384 🐺"

Max Length

generateSlug({ maxLength: 12 })
// "brave-golden" (trimmed cleanly)

generateSlugs(count, options?)

Generate multiple unique slugs at once. It automatically increments the PRNG seed if configured.

import { generateSlugs } from "random-words-slugs";

generateSlugs(5)
// ["brave-golden-fox", "tiny-cyan-wolf", "bold-silver-hawk", ...]

generateSlugs(3, { format: "pascal", appendNumber: true })
// ["BraveGoldenFox42", "TinyCyanWolf7", "BoldSilverHawk199"]

countUniqueSlugs(options?)

Count how many unique slug combinations are possible.

import { countUniqueSlugs } from "random-words-slugs";

countUniqueSlugs()
// 831,744  (based on default word lists)

countUniqueSlugs({ wordCount: 2 })
// 5,152

countUniqueSlugs({ wordCount: 4 })
// e.g. 51,380,736

Word Categories

| Category | Example words | |-------------|----------------------------------------| | adjective | brave, golden, tiny, cyber, cosmic ... | | noun | fox, river, rocket, pixel, nebula ... | | verb | soars, glows, hunts, dances, pulses ... | | adverb | swiftly, boldly, silently, keenly ... |

License

MIT