culler

culler is a utility library designed to create, manipulate, convert, and apply colors. It supports RGB, RGBA, and HEX color formats and is written in TypeScript, providing extensive type safety. Additionally, the library ensures integration into any Node.js project by maintaining backward compatibility with CommonJS imports.

Features

  • Generate random RGB, RGBA, and HEX color strings.
  • Convert color values between formats, including semi-transparent and solid colors.
  • Apply colors to a CSS selector string, HTML element, or an iterable containing HTML Elements.
  • Includes a random number generator with configurable parameters.
  • Designed to be lightweight and efficient.


Getting started

Note

Node.js and NPM are required to install culler.

Installation

Run the following command to install culler using npm:

npm install culler

Usage

CommonJS (CJS)

const culler = require("culler")

ECMAScript (ESM)

import culler from "culler"

Tip

Destructure the imports as shown in the following sample.

import {gen, apply, convert} from "culler"


apply() Syntax

Specify the element and color value to apply:

culler.apply(ApplyQuery, color: Color)

apply() Samples

Apply color to a Nodelist:

const cardEls = document.querySelectorAll(".card")
culler.apply(cardEls, "rgb(25, 12, 92)")

Apply color to a cached element:

const element = document.getElementbyId("elementID")
culler.apply(element, "#FF00FF")

Apply color using a CSS selector:

culler.apply("ul > li:nth-child(3)", "aliceblue")
// Selects every third `li` in `ul` and sets the `background-color` property to aliceblue.


gen() Syntax

Specify the color format (rgb, rgba, or hex) to generate random colors. Enable transparency by setting alpha to true. To limit the range of colors, include the miniumum and maximum values to generate for the red, green, and blue channels. Alternatively, define specific colors by including the exact values of the red, green, blue, and alpha channels.

culler.gen(userOptions: genOptions)

gen() Samples

Generate random colors:

const randomColor = culler.gen()

Note

The default output without specifying options is a random rgba string.

Generate random HEX colors:

const hexColor = culler.gen({ type: "hex" })

Note

The full range of color is enabled by default unless specified otherwise.

Generate colors within specified limits:

const greenishColor = culler.gen({ type: "rgb", minG: 200 })
// Generates a green-dominant rgb color every time.

Generate specific colors:

const notGreenAtAll = culler.gen({ g: 0 })


convert() Syntax

Specify the color type and value to convert colors between rgb, rgba, and hex.

culler.convert(color: Color, to: "rgb" | "rgba" | "hex")

convert() Samples

rgba to hex:

const rgbaToHex = culler.convert("rgba(13, 35, 55, 0.7)", "hex")
// #0d2337b2

hex to rgb:

const hexToRgb = culler.convert("#F8DE0F", "rgb") 
// rgb(248, 222, 15)

rgba to rgb:

const rgbaToRgb = culler.convert("rgba(154, 25, 118, 0.35)", "rgb") 
// rgb(219, 174, 207)

Note

Converting rgba to rgb will result in an identical color overlayed on a white background.


genNum() Syntax

Culler includes a utility to randomly generate numbers.

culler.genNum(userOptions: genNumOptions)

genNum() Samples

Generate a random number between 0 and 1:

const floatBetween0and1 = culler.genNum()

Note

The default behavior without specifying options is similar to Math.random() and will generate a float between 0 and 1.

Generate random numbers within specified limits:

const intBetween66and942 = culler.genNum({ min: 66, max: 942, isInt: true })

Limit the decimal places when generating floats:

const floatTo5DecimalPlaces = culler.genNum({ clamp: 5 })


Type Definitions

type ApplyQuery =
    | HTMLElement
    | HTMLCollection
    | NodeList
    | NodeListOf<Element>
    | string // CSS selector string

type RGB = `rgb(${number}, ${number}, ${number})`
type RGBA = `rgba(${number}, ${number}, ${number}, ${number})`
type HEX = `#${string}`

type Color = RGB | RGBA | HEX | CSSNamedColor

type ColorTypes = "rgb" | "rgba" | "hex"

type genOptions = {
    type?: ColorTypes  // type of color string generated   - default: rgba
    alpha?: boolean // Allow transparency                              - default: true
    minR?: number   // Minimum value to generate for the red channel   - default: 0
    maxR?: number   // Maximum value to generate for the red channel   - default: 255
    minG?: number   // Minimum value to generate for the green channel - default: 0
    maxG?: number   // Maximum value to generate for the green channel - default: 255
    minB?: number   // Minimum value to generate for the blue channel  - default: 0
    maxB?: number   // Maximum value to generate for the blue channel  - default: 255
    r?: number      // Explicitly set the value for the red channel    - default: undefined
    g?: number      // Explicitly set the value for the blue channel   - default: undefined
    b?: number      // Explicitly set the value for the green channel  - default: undefined
    a?: number      // Explicitly set the value for the alpha channel  - default: undefined
}

type genNumOptions = {
    min?: number      // minimum number                                - default: 0
    max?: number      // maximum number                                - default: 1
    isInt?: boolean   // false for float, true for int                 - default: false
    clamp?: number    // clamp num to this many decimal places (0-16)  - default: 2
}

type convertOptions = {
    color: Color
    to?: ColorTypes
}