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";

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:273

---

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

---

complimentary()

complimentary(baseColor, options): ColorToken

Returns the complimentary color of the passed in color token. A complimentary color is 180 degrees away on the hue channel.

Parameters

• baseColor: ColorToken

The color to retrieve its complimentary equivalent.

• options: ComplimentaryOptions = ...

Optional overrides to customize behaviour.

Returns

ColorToken

Example

import { complimentary } from "huetiful-js";

console.log(complimentary("pink", true))
//// { hue: 'blue-green', color: '#97dfd7ff' }

console.log(complimentary("purple"))
// #005700

Defined in

utils.ts:808

---

family()

family(color): 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.

Returns

BiasedHues & ColorFamily

Example

import { family } from 'huetiful-js'

console.log(family("#310000"))
// 'red'

Defined in

utils.ts:695

---

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 = 'cyan'

The color to darken.

• 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:317

---

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 = 'cyan'

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:627

---

mc()

mc<Value>(modeChannel): (color, value?) => Value extends string | 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.

Type Parameters

• Value

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

Parameters

• color: ColorToken = 'cyan'

• value?: string | number

Returns

Value extends string | number ? ColorToken : number

Example

| *
import { mc } from 'huetiful-js'

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

Defined in

utils.ts:181

---

overtone()

overtone(color): ColorFamily | false

Returns the name of the hue family which is biasing the passed in color using the 'lch' colorspace.

• If an achromatic color is passed in it returns the string 'gray'
• If the color has no bias it returns false.

Parameters

• color: ColorToken = 'cyan'

The color to query its overtone.

Returns

ColorFamily | false

Example

import { overtone } from "huetiful-js";

console.log(overtone("fefefe"))
// 'gray'

console.log(overtone("cyan"))
// 'green'

console.log(overtone("blue"))
// false

Defined in

utils.ts:779

---

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]));
// false

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

// [ true,  false, true]

Defined in

utils.ts:741

---

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:372