Skip to main content

What's new ?

Prior to v3 the API was not very DRY, with utilities being over specialised for one particular task. Most notably, the sortBy and filterBy utilities have been merged and are now customizable through an options object.

Slimmer API​

filterBy​

You can now get your passed in collection filtered using different factors and ranges for each factor.

import { filterBy } from "huetiful-js";

// before
filterByHue(...)
filterBySaturation(...)
filterByLuminance(...)

// after
filterBy(...,{ factors:['hue','chroma','luminance'],
ranges:{
	hue:[...],
	chroma:[...],
	luminance:[...]
}})

sortBy​

import { sortBy } from "huetiful-js";

// before
sortByHue(...)
sortBySaturation(...)
sortByLuminance(...)

// after
sortBy(...,{ factor:['hue','chroma','luminance'], order:'desc' })

Easier to customize iteration behaviour than maintain small functions

token​

"One parser to rule convert them all"

Initially each color token type had a standalone converter function. All these functions have been merged into one function, which can parse and output color tokens in different types.

// Old syntax
import { num2rgb, toHex } from 'huetiful-js'

let cssNamedColor = 'pink'
let colorNumber = 5000
let colorObject = { l: 50, c: 20, h: 40, mode: 'lch' }
let colorObjectWithAlpha = { l: 50, c: 20, h: 40, alpha: 0.5, mode: 'lch' }
let arrColor = ['rgb', 120, 80, 50]
let arrColorWithAlpha = ['rgb', 120, 80, 50, 0.1]

// any of the above color tokens is valid

token(...)

Method chaining with color() and load()​

Method chaining allows a more concise and readable syntax than nesting functions inside of each other.

Smaller bundle​

The library now supports a limited number of colorspaces because the mode definitions make the bundle really large.

tip

See the Culori docs for more information on colorspaces that are included by default. For conversion across many colorspaces use the Culori library instead.

Below is an exhaustive list of supported colorpaces:


export type Colorspaces =
   | 'lab'
   | 'lab65'
   | 'rgb'
   | 'lch'
   | 'lch65'
   | 'xyz65'
   | 'xyz'


A few more collection methods​

caution

These functions are still experimental and may have breaking changes in future versions.

stats()​

This function gets the statistics for a collection of color tokens alongside some extra meta which can be useful when you want to know certain info before making a decision during color manipulation. It also has an options object to customize how the stats are calculated.

distribute()​

As the name suggests, this function opens a new avenue of creativity by distributing the specified factors equally amongst other color tokens in the collection. Its behaviour can also be customized by passing an options object.

tip

If you think this function can be further improved, [open an issue](https://github.com/prjctimg/huetiful/issues/new0 on the project repository alongside some suggestions you may have in mind!

Better types and code examples​

The library is written in TypeScript for better editor autocomplete support and type definitions for the API. The code examples have also been updated to be more simple and straightforward.

tip

Made something cool out of this ? You can share it on my Twitter.

I'd love to see what can be built with this project!

I hope you find this update useful! πŸš€