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
}