Random CSS Value Generator

A simple, lightweight, and fast javascript library for generating random css values with customizable parameters for various css data types commonly used in web development.

Installation

npm install css-value-randomize

Usage Example

import { randomize } from 'css-value-randomize'

const random = randomize({
  /*configuration here */
})

console.log(random.integer({ min: 1, max: 100 }))

Available Generators

integer

Generate random integer values.

Options

interface IntegerParams {
  min?: number
  max?: number
  step?: number
}

• min - Set smallest possible value (default: 0)
• max - Set largest possible value (default: 100)
• step - Set step between values (default: 1)

Example

random.integer({ min: 10, max: 20, step: 2 })
// Returns: 12, 14, 16, 18, or 20

number

Generate random numeric values with decimal support.

Options

interface NumberParams {
  min?: number
  max?: number
  decimalMin?: number
  decimalMax?: number
  allowDecimal?: boolean
  decimalPlaces?: number
  step?: number | null
}

• min - Set smallest possible integer value (default: 0)
• max - Set largest possible integer value (default: 100)
• decimalMin - Set smallest possible decimal value (default: 0)
• decimalMax - Set largest possible decimal value (default: 10)
• allowDecimal - Allow decimal numbers (default: true)
• decimalPlaces - Number of decimal places (default: 2)
• step - Set step between values, overrides decimal logic (default: null)

Example

random.number({ min: 1, max: 10, decimalPlaces: 1 })
// Returns: 7, 3.5, 8.2, etc.

length

Generate CSS length values with units.

Options

interface LengthParams {
  units?: string[]
  min?: number
  max?: number
  decimalMin?: number
  decimalMax?: number
  allowNegative?: boolean
  allowZero?: boolean
  weightedUnits?: WeightedItem[] | null
}

• units - Array of CSS units (default: ['px', 'rem', 'em', '%', 'vh', 'vw', 'ch', 'dvh', 'svh', 'vmin', 'vmax'])
• min - Set smallest possible value (default: 0)
• max - Set largest possible value (default: 100)
• decimalMin - Set smallest possible decimal value (default: 0)
• decimalMax - Set largest possible decimal value (default: 10)
• allowNegative - Allow negative values (default: false)
• allowZero - Allow zero values (default: true)
• weightedUnits - Weighted unit selection (default: null)

Example

random.length({ min: 10, max: 50, units: ['px', 'rem'] })
// Returns: "25px", "1.5rem", "42px", etc.

percentage

Generate percentage values.

Options

interface PercentageParams {
  min?: number
  max?: number
  decimalPlaces?: number
}

• min - Set smallest possible value (default: 0)
• max - Set largest possible value (default: 100)
• decimalPlaces - Number of decimal places (default: 1)

Example

random.percentage({ min: 0, max: 100, decimalPlaces: 2 })
// Returns: "45.67%", "12.34%", "89.01%", etc.

angle

Generate angle values with units.

Options

interface AngleParams {
  units?: string[]
  min?: number
  max?: number
  allowNegative?: boolean
}

• units - Array of angle units (default: ['deg', 'rad', 'grad', 'turn'])
• min - Set smallest possible value (default: 0)
• max - Set largest possible value (default: 360)
• allowNegative - Allow negative values (default: true)

Example

random.angle({ min: 0, max: 180, units: ['deg'] })
// Returns: "45deg", "120deg", "90deg", etc.

time

Generate time duration values.

Options

interface TimeParams {
  units?: string[]
  min?: number
  max?: number
  decimalPlaces?: number
}

• units - Array of time units (default: ['s', 'ms'])
• min - Set smallest possible value (default: 0)
• max - Set largest possible value (default: 5)
• decimalPlaces - Number of decimal places (default: 2)

Example

random.time({ min: 0.1, max: 2, units: ['s'] })
// Returns: "1.25s", "0.75s", "1.89s", etc.

frequency

Generate frequency values.

Options

interface FrequencyParams {
  units?: string[]
  min?: number
  max?: number
}

• units - Array of frequency units (default: ['Hz', 'kHz'])
• min - Set smallest possible value (default: 20)
• max - Set largest possible value (default: 20000)

Example

random.frequency({ min: 100, max: 1000, units: ['Hz'] })
// Returns: "440Hz", "880Hz", "220Hz", etc.

resolution

Generate resolution values for display density.

Options

interface ResolutionParams {
  units?: string[]
  min?: number
  max?: number
}

• units - Array of resolution units (default: ['dpi', 'dpcm', 'dppx'])
• min - Set smallest possible value (default: 72)
• max - Set largest possible value (default: 300)

Example

random.resolution({ min: 96, max: 300, units: ['dpi'] })
// Returns: "144dpi", "192dpi", "96dpi", etc.

color

Generate color values in various formats.

Options

interface ColorParams {
  format?: 'auto' | 'named' | 'hex' | 'rgb' | 'hsl'
  includeAlpha?: boolean
  preferNamed?: number
  colors?: string[]
}

• format - Color format to generate (default: 'auto')
• includeAlpha - Include alpha channel (default: false)
• preferNamed - Preference weight for named colors when format is 'auto' (default: 0.2)
• colors - Array of named colors to choose from (default: ['red', 'blue'])

Example

random.color({ format: 'hex', includeAlpha: true })
// Returns: "#ff6b35ff", "#2e8bc0", "#b1a296", etc.

random.color({ format: 'rgb' })
// Returns: "rgb(255, 107, 53)", "rgb(46, 139, 192)", etc.

string

Generate random string values.

Options

interface StringParams {
  minLength?: number
  maxLength?: number
  charset?: 'alphanumeric' | 'alpha' | 'words'
}

• minLength - Minimum string length (default: 3)
• maxLength - Maximum string length (default: 12)
• charset - Character set to use (default: 'alphanumeric')

Example

random.string({ minLength: 5, maxLength: 10, charset: 'alpha' })
// Returns: "AbCdEf", "XyZabc", "QwErTy", etc.

random.string({ charset: 'words' })
// Returns: "lorem ipsum", "dolor sit", etc.

url

Generate URL values.

Options

interface UrlParams {
  protocol?: string
  extensions?: string[]
  domains?: string[]
}

• protocol - URL protocol (default: 'https')
• extensions - Array of file extensions (default: ['.jpg', '.png', '.svg', '.webp', '.gif'])
• domains - Array of domain names (default: ['example.com', 'placeholder.com', 'via.placeholder.com', 'github.com'])

Example

random.url({ protocol: 'https', extensions: ['.jpg', '.png'] })
// Returns: 'url("https://example.com/abc123.jpg")', etc.

Global Configuration

You can set default options for all methods at once:

const random = randomize({
  integer: { min: 1, max: 1000 },
  color: { format: 'hex', includeAlpha: true },
  length: { units: ['px', 'rem'], allowNegative: false }
})

// These defaults will be merged with any parameters passed to individual generators
random.integer() // Uses min: 1, max: 1000
random.integer({ max: 50 }) // Uses min: 1, max: 50

Custom Generator

You can extend the random with custom plugins:

const random = randomize({
  custom: {
    customGenerator: (params) => {
      // Your custom logic here
      return 'custom-value'
    }
  }
})

random.customGenerator() // Returns: "custom-value"

License

MIT © 2025 NOuSantx