Skip to main content

Utils

Functions​

achromatic()​

achromatic(color): boolean

Checks if a color token is achromatic (without hue or simply grayscale).

Parameters​

β€’ color: ColorToken = "cyan"

The color token to test if it is achromatic or not.

Returns​

boolean

Example​

import { achromatic } from "huetiful-js";
S
achromatic('pink')
// false

let sample = [
 "#164100",
 "#ffff00",
 "#310000",
 'pink'
];

console.log(sample.map(achromatic));

// [false, false, false,false]

achromatic('gray')
// Returns true

// We can expand this example by interpolating between black and white and then getting some samples to iterate through.

import { interpolator } from "huetiful-js"

// we create an interpolation using black and white with 12 samples
let grays = interpolator(["black", "white"],{ num:12 });

console.log(grays.map(achromatic));

//
[false, true, true,
 true,  true, true,
 true,  true, true,
 true,  true, false
]

Defined in​

utils.ts:258

alpha()​

alpha<Amount>(color, amount): Amount extends undefined ? number : ColorToken

Returns the color token's alpha channel value.

If the the amount parameter is passed in, it sets the color token's alpha channel with the amount specified and returns the color as a hex string.

tip
  • Also supports math expressions as a string for the amount parameter. For example *0.5 which means the value multiply the current alpha by 0.5 and set the product as the new alpha value. In short currentAlpha * 0.5 = newAlpha. The supported symbols are * - / +.

If the alpha channel is undefined, it defaults to 1.

Type Parameters​

β€’ Amount

Parameters​

β€’ color: ColorToken = "cyan"

The color with the opacity/alpha channel to retrieve or set.

β€’ amount: Amount = undefined

The value to apply to the opacity channel. The value is between [0,1]

Returns​

Amount extends undefined ? number : ColorToken

Example​

import { alpha } from 'huetiful-js'

// Getting the alpha
console.log(alpha('#a1bd2f0d'))
// 0.050980392156862744

// Setting the alpha

let myColor = alpha('b2c3f1', 0.5)

console.log(myColor)

// #b2c3f180

Defined in​

utils.ts:87

family()​

family(color?, bias?): BiasedHues & ColorFamily | {bias: false | ColorFamily;hue: BiasedHues & ColorFamily; }

Gets the hue family which a color belongs to with the overtone included (if it has one.).

For example 'red' or 'blue-green'. If the color is achromatic it returns the string 'gray'.

Parameters​

β€’ color?: ColorToken

The color to query its shade or hue family.

β€’ bias?: boolean = false

Returns the name of the hue family which is biasing the passed in color using the 'lch' colorspace. If it has no bias it returns false on the bias property of the returned object.

note

This bias parameter replaces the overtone() function.

Returns​

BiasedHues & ColorFamily | {bias: false | ColorFamily;hue: BiasedHues & ColorFamily; }

Example​

import { family } from 'huetiful-js'

console.log(family("#310000"))

// 'red'

Defined in​

utils.ts:672

lightness()​

lightness(color?, options?): ColorToken

Darkens the color by reducing the lightness channel by amount of the channel. For example 0.3 means reduce the lightness by 0.3 of the channel's current value.

Parameters​

β€’ color?: ColorToken

The color to darken or lighten.

β€’ options?: LightnessOptions = ...

Returns​

ColorToken

Example​

import { lightness } from "huetiful-js";

// darkening a color
console.log(lightness('blue', 0.3, true));

// '#464646'

// brightening a color, we can omit the final param
// because it's false by default.
console.log(brighten('blue', 0.3));
//#464646

Defined in​

utils.ts:301

luminance()​

luminance<Amount>(color?, amount?): Amount extends number ? ColorToken : number

Gets the luminance of the passed in color token.

If the amount parameter is passed in, it will adjust the luminance by interpolating the color with black (to decrease luminance) or white (to increase the luminance) by the specified amount.

Type Parameters​

β€’ Amount

Parameters​

β€’ color?: ColorToken

The color to retrieve or adjust luminance.

β€’ amount?: number = undefined

The amount of luminance to set. The value range is normalised between [0,1]

Returns​

Amount extends number ? ColorToken : number

Example​

import { luminance } from 'huetiful-js'

// Getting the luminance

console.log(luminance('#a1bd2f'))
// 0.4417749513730954

console.log(colors('all', '400').map((c) => luminance(c)));

// [
  0.3595097699638928,  0.3635745068550118,
  0.3596908494424909,  0.3662525955988395,
 0.36634113914916244, 0.32958967582076004,
 0.41393242740130043,  0.5789820793721787,
  0.6356386777636567,  0.6463720036841869,
  0.5525691083297639,  0.4961850321908156,
  0.5140644334784611,  0.4401325598899415,
 0.36299191043315415,  0.3358285501372504,
 0.34737270839643575, 0.37670102542883394,
  0.3464512307705231, 0.34012939384198054
]

// setting the luminance

let myColor = luminance('#a1bd2f', 0.5)

console.log(luminance(myColor))
// 0.4999999136285792

Defined in​

utils.ts:597

mc()​

mc(modeChannel): <Value>(color?, value?) => Value extends number ? ColorToken : number

Sets the value of the specified channel on the passed in color.

If the amount parameter is undefined it gets the value of the specified channel.

Parameters​

β€’ modeChannel: string = "lch.h"

The mode and channel to be retrieved. For example 'rgb.b' will return the value of the blue channel in the RGB color space of that color.

Returns​

Function

Type Parameters​

β€’ Value extends unknown

Parameters​

β€’ color?: ColorToken

β€’ value?: Value

Returns​

Value extends number ? ColorToken : number

Example​

import { mc } from 'huetiful-js'

console.log(mc('rgb.g')('#a1bd2f'))
// 0.7411764705882353

Defined in​

utils.ts:177

temp()​

temp(color): "cool" | "warm"

Returns a rough estimation of a color's temperature as either 'cool' or 'warm' using the 'lch' colorspace.

Parameters​

β€’ color: ColorToken = "cyan"

The color to check the temperature. True if the color is cool else false.

Returns​

"cool" | "warm"

Example​

import { temp } from 'huetiful-js'

let sample = [
 "#00ffdc",
 "#00ff78",
 "#00c000"
];

console.log(temp(sample[2]));
// 'cool'

console.log(map(sample, temp));

// [ 'cool',  'warm', 'cool']

Defined in​

utils.ts:724

token()​

token(color, options?): ColorToken

Parses any recognizable color to the specified kind of ColorToken type.

The kind option supports the following types as options:

  • 'arr' - Parses the color token to an array of channel values with the colorspace as the first element if the omitMode parameter is set to false in the options object.

  • 'num' - Parses the color token to its numerical equivalent to a number between 0 and 16,777,215.

The numberType can be used to specify which type of number to return if the kind option is set to 'number':

  • 'hex' - Hexadecimal number
  • 'bin' - Binary number
  • 'oct' - Octal number
  • 'expo' - Decimal exponential notation

  • 'str' - Parses the color token to its hexadecimal string equivalent.

  • 'obj' - Parses the color token to a plain color object in the mode specified by the targetMode parameter in the options object.t

tip

If the color token has an explicit alpha (specified by the alpha key in color objects and as the fourth and last number in a color array) the string will be 8 characters long instead of 6.

Parameters​

β€’ color: ColorToken = "cyan"

The color token to parse or convert.

β€’ options?: TokenOptions

Options to customize the parsing and output behaviour.

Returns​

ColorToken

Defined in​

utils.ts:356