@nextcss/color-tools

Color Tools

Useful tools when working with colors.

• Introduction
• Compatibility
• Installation
• HEX to RGB
• RGB to HEX
• HSL to HEX
• Color Shift
• Tone Map
• Brightness
• Colorify
• Random HEX
• Random RGB
• Random HSL
• Guidelines
• License

Introduction

This package is a module of the nextcss project. This package was created to maintain this module independently of the main package and to be used as a building block in other projects.

Compatibility

This package can be used in both browser and node environments. Includes both ES Modules and CommonJS versions, so you can safely use both import and require statements in any environment. In the examples I'll use the import syntax, so don't be scared, feel free to use the require syntax if you like, that will work too. TypeScript support is also available.

Installation

Install the package via yarn or npm.

yarn add -D @nextcss/color-tools

npm i -D @nextcss/color-tools

HEX to RGB

Convert hexadecimal color (3, 6 or 8 digits) to RGB color array.

Syntax

const Array = hex2rgb(hex: String);

Example

import { hex2rgb } from "@nextcss/color-tools";

const rgb1 = hex2rgb("#eee");
console.log(rgb1);
// Output → [ 238, 238, 238 ]

const rgb2 = hex2rgb("#2196f3");
console.log(rgb2);
// Output → [ 33, 150, 243 ]

const rgb3 = hex2rgb("#2196f3bf");
console.log(rgb3);
// Output → [ 33, 150, 243, 75 ]
// the last element is alpha, defined as a percentage

const [red, green, blue, alpha] = hex2rgb("#2196f3bf");
console.log({ red, green, blue, alpha });
// Output → { red: 33, green: 150, blue: 243, alpha: 75 }
// Example RGB string → rgb(33 150 243 / 75%)
// Example RGBA string → rgba(33, 150, 243, .75)

RGB to HEX

Convert RGB color array [red, green, blue, alpha?] to hexadecimal color.

Syntax

const String = rgb2hex(rgb: Array);

Example

import { rgb2hex } from "@nextcss/color-tools";

const hex1 = rgb2hex([238, 238, 238]);
console.log(hex1);
// Output → '#eeeeee'

const hex2 = rgb2hex([238, 238, 238, 75]);
console.log(hex2);
// Output → '#eeeeeebf'

HSL to HEX

Convert HSL color array [hue,saturation,lightness] to hexadecimal color.

Syntax

const String = hsl2hex(hsl: Array);

Example

import { hsl2hex } from "@nextcss/color-tools";

const hex1 = hsl2hex([200, 70, 50]);
console.log(hex1);
// Output → #269dd9

const hex2 = hsl2hex([36, 90, 40]);
console.log(hex2);
// Output → #c2780a

Color Shift

Shift a hexadecimal color (3, 6 or 8 digits) by the specified percentage. Positive shift results lighter colors, negative shift results darker colors.

Syntax

const String = colorShift(hex: String, percentage: Number);

Example

import { colorShift } from "@nextcss/color-tools";

const color = colorShift("#eee", 10);
console.log(color);
// Output → #d6d6d6

const color2 = colorShift("#eee", -10);
console.log(color2);
// Output → #f0f0f0

Tone Map

Generate a tone map from a hexadecimal color (3, 6 or 8 digits), between 50 and 950 tones.

Syntax

const Object = toneMap(hex: String);

Example

import { toneMap } from "@nextcss/color-tools";

const tones = toneMap("#eee");
console.log(tones);
// Output → {
//   50: '#fdfdfd',
//   100: '#fcfcfc',
//   150: '#fbfbfb',
//   200: '#f9f9f9',
//   250: '#f7f7f7',
//   300: '#f5f5f5',
//   350: '#f3f3f3',
//   400: '#f1f1f1',
//   450: '#f0f0f0',
//   500: '#eeeeee',
//   550: '#d6d6d6',
//   600: '#bebebe',
//   650: '#a7a7a7',
//   700: '#8f8f8f',
//   750: '#777777',
//   800: '#5f5f5f',
//   850: '#474747',
//   900: '#303030',
//   950: '#242424',
// }

Brightness

Calculate brightness (percentage) of a hexadecimal color. For example, if the color brightness is <50, the color is dark, otherwise it is light.

Syntax

const Number = brightness(hex: String);

Example

import { brightness } from "@nextcss/color-tools";

const level1 = brightness("#000");
console.log(level1);
// Output → 0

const level2 = brightness("#ffffff");
console.log(level2);
// Output → 100

const level3 = brightness("#269dd9");
console.log(level3);
// Output → 53

Colorify

Generate a hexadecimal color from any string (like username). Under the hood, it uses HSL to create the color, so you can set saturation (default: 50) and lightness (default: 50) values as an input.

Syntax

const String = colorify(str: String, saturation?: Number, lightness?: Number);

Example

import { colorify } from "@nextcss/color-tools";

const hex1 = colorify("John Doe");
console.log(hex1);
// Output → #40bf79

const hex2 = colorify("JD", 60);
console.log(hex2);
// Output → #3394cc

const hex3 = colorify("J", 60, 80);
console.log(hex3);
// Output → #dcebad

Random HEX

Generate a random hexadecimal color. Under the hood, it uses HSL to create the color, so you can set the saturation (default: 70) and lightness (default: 50) values as an input.

Syntax

const String = randomHex(saturation?: Number, lightness?: Number);

Example

import { randomHex } from "@nextcss/color-tools";

const hex1 = randomHex();
console.log(hex1);
// Output → #7de889

const hex2 = randomHex(50);
console.log(hex2);
// Output → #b38cd9

const hex3 = randomHex(65, 80);
console.log(hex3);
// Output → #abbbed

Random RGB

Generate a random RGB color array. Under the hood, it uses HSL to create the color, so you can set the saturation (default: 70) and lightness (default: 50) values as an input.

Syntax

const Array = randomRgb(saturation?: Number, lightness?: Number);

Example

import { randomRgb } from "@nextcss/color-tools";

const rgb1 = randomRgb();
console.log(rgb1);
// Output → [ 232, 193, 125 ]

const rgb2 = randomRgb(50);
console.log(rgb2);
// Output → [ 217, 161, 140 ]

const rgb3 = randomRgb(65, 80);
console.log(rgb3);
// Output → [ 206, 171, 237 ]

Random HSL

Generate a random HSL color array. Under the hood, it uses HSL to create the color, so you can set the saturation (default: 70) and lightness (default: 50) values as an input.

Syntax

const Array = randomHsl(saturation?: Number, lightness?: Number);

Example

import { randomHsl } from "@nextcss/color-tools";

const hsl1 = randomHsl();
console.log(hsl1);
// Output → [ 294, 70, 50 ]

const hsl2 = randomHsl(50);
console.log(hsl2);
// Output → [ 79, 50, 50 ]

const hsl3 = randomHsl(65, 80);
console.log(hsl3);
// Output → [ 274, 65, 80 ]

Guidelines

To learn about the guidelines, please read the Code of Conduct, Contributing and Security Policy documents.

License

MIT License @ 2022 Zsolt Tövis

If you found this project interesting, please consider supporting my open source work by sponsoring me / give the repo a star / follow the nextcss project.