Random Utility Classes Generator

This package is a lightweight and fast random utility-first or atomic CSS (like TailwindCSS or UnoCSS) class names generator.

Installation

npm i random-utility-class

Usage

import { generate } from 'random-utility-class'

const types = {
  text: ['<color>', '<number>'],
  bg: ['<color>', 'fixed', 'scroll'],
  flex: ['<no-value>', '<number>', () => (Math.random() < 0.5 ? 'row' : 'col')],
  p: ['<integer>', '<length>']
}

const classNames = generate({
  count: 5,
  types,
  variants: ['hover', 'focus', 'dark', 'max-md'],
  noDuplicates: true, // Prevent duplicate class names

  // singular value generator option
  // see https://github.com/nousantx/css-value-randomize
  length: {
    decimalMax: 400
  }
})

console.log(classNames)

Output example:

;['text-yellow', 'bg-lightcyan', 'focus:bg-pink', 'flex', 'hover:p-4']

Configuration Options

Basic Options

• count (number): Number of class names to generate (default: 1)
• types (object): Property-value type mappings
• variants (array): CSS variants like hover, focus, dark mode, etc.
• noDuplicates (boolean): Prevent duplicate class names (default: false)

Value Generator Options

You can customize the generation of different value types:

• color: Color generation options
• integer: Integer value options
• number: Number value options
• length: Length unit options
• percentage: Percentage options
• angle: Angle options
• time: Time unit options
• frequency: Frequency options
• resolution: Resolution options
• string: String generation options
• url: URL generation options
• custom: Custom value generators

See css-value-randomize documentation for more.

Available Built-in Types

export type AllowedTypes =
  | '<no-value>' // For valueless classes like 'flex'
  | '<integer>' // Whole numbers
  | '<number>' // Decimal numbers
  | '<length>' // CSS length units (px, em, rem, etc.)
  | '<percentage>' // Percentage values
  | '<time>' // Time units (s, ms)
  | '<frequency>' // Frequency units (Hz, kHz)
  | '<resolution>' // Resolution units (dpi, dpcm)
  | '<color>' // Color values
  | '<string>' // String values
  | '<url>' // URL values
  | (() => string) // Custom functions
  | string // Static string values

Examples

Basic Usage

const classNames = generate({
  count: 3,
  types: {
    bg: ['<color>'],
    text: ['<color>'],
    p: ['<integer>']
  }
})
// Output: ['bg-[rgb(165,_98,_76)]', 'text-[#ccf654]', 'p-4']

With Variants

const classNames = generate({
  count: 5,
  types: {
    bg: ['<color>'],
    text: ['<color>']
  },
  variants: ['hover', 'focus', 'dark']
})
// Output: ['bg-[#9ed5e8]', focus:text-[rgb(83,_89,_199)]', 'text-[rgb(41,_200,_24)]', 'focus:bg-[hsl(56,_41%,_71%)]', 'dark:bg-[#a1f955]']

Valueless Classes

const classNames = generate({
  count: 3,
  types: {
    flex: ['<no-value>'],
    block: ['<no-value>'],
    hidden: ['<no-value>']
  }
})
// Output: ['flex', 'block', 'hidden']

Custom Value Generators

const classNames = generate({
  count: 4,
  types: {
    grid: ['<custom-cols>'],
    text: ['<custom-size>']
  },
  custom: {
    'custom-cols': () => `cols-${Math.floor(Math.random() * 12) + 1}`,
    'custom-size': () => ['xs', 'sm', 'base', 'lg', 'xl'][Math.floor(Math.random() * 5)]
  }
})
// Output: ['grid-cols-3', 'text-lg', 'grid-cols-8', 'text-xs']

No Duplicates

const classNames = generate({
  count: 10,
  types: {
    p: ['<integer>'],
    m: ['<integer>']
  },
  noDuplicates: true
})
// Ensures all 10 generated classes are unique

Mixed Types

const classNames = generate({
  count: 6,
  types: {
    bg: ['<color>', 'gradient-to-r', 'fixed'],
    text: ['<color>', '<number>', () => (Math.random() < 0.5 ? 'uppercase' : 'lowercase')],
    flex: ['<no-value>', '<number>']
  },
  variants: ['hover', 'focus', 'dark', 'lg'],
  noDuplicates: true
})
// Output: ['bg-blue', 'hover:text-1.2', 'flex', 'focus:bg-gradient-to-r', 'text-lowercase', 'dark:flex-2']

License

MIT © 2025 NOuSantx