colorizr
Version:
Manipulate colors like a boss
778 lines (548 loc) • 19.3 kB
Markdown
# Colorizr
[](https://www.npmjs.com/package/colorizr) [](https://bundlephobia.com/result?p=colorizr) [](https://github.com/gilbarbara/colorizr/actions/workflows/main.yml) [](https://sonarcloud.io/summary/new_code?id=gilbarbara_colorizr) [](https://sonarcloud.io/summary/new_code?id=gilbarbara_colorizr)
Color conversion, generation, manipulation, comparison, and analysis.
## Highlights
- 🏖 **Easy to use**: Works with Hex, HSL, OkLab, OkLCH, and RGB.
- ♿️ **Accessibility:** WCAG analysis and comparison.
- 🛠 **Small:** 7kB (gzipped) and tree-shakable.
- 🟦 **Modern:** Written in Typescript.
## Setup
**Install**
```bash
npm i colorizr
```
## Usage
You can use all the functions standalone:
```typescript
import { luminance } from 'colorizr';
const lux = luminance('#ff0044'); // 0.2168
```
Or you can create an instance to use all the methods for the same color:
```typescript
import Colorizr from 'Colorizr';
const colorInstance = new Colorizr('#ff0044');
colorInstance.luminance; // 0.2168
colorInstance.chroma; // 1
colorInstance.opacity; // 1
```
## API
> String inputs accept css values: hex, hsl, oklab, oklch, rgb, and named colors.
- [Info](#Info)
- [Manipulators](#Manipulators)
- [Converters](#Converters)
- [Generators](#Generators)
- [Comparison](#Comparison)
- [Utilities](#Utilities)
- [Validators](#Validators)
- [Class](#Class)
### Info
**chroma(input: string): number**
Get the chroma of a color.
```typescript
import { chroma } from 'colorizr';
chroma('#ff0044'); // 1
chroma('#ffc0cb'); // 0.2471
```
**luminance(input: string): number**
Get the relative brightness according to the [WCAG definition](https://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef).
Normalized to `0` for black and `1` for white.
```typescript
import { luminance } from 'colorizr';
luminance('#ff0044'); // 0.2168
```
**name(input: string): string**
Get the name of a color. Return the hex code if it can't be named.
```typescript
import { name } from 'colorizr';
name('#ffc0cb'); // pink
name('rgb(176 224 230)'); // 'powderblue'
name('hsl(344 100 50)'); // #ff0044
```
**opacity(input: string): string**
Get the opacity of a color.
```typescript
import { opacity } from 'colorizr';
opacity('#ff0044'); // 1
opacity('rgb(255 0 68 / 90%)'); // 0.9
opacity('hsl(344 100 50 / 60%)'); // 0.6
```
### Manipulators
**lighten(input: string, amount: number): string**
Get a color with increased lightness.
```typescript
import { lighten } from 'colorizr';
lighten('#ff0044', 10); // #ff3369
lighten('hsl(136 100% 50%)', 10); // hsl(136 100% 60%)
```
**darken(input: string, amount: number): string**
Get a color with decreased lightness.
```typescript
import { darken } from 'colorizr';
darken('#ff0044', 10); // #cc0036
darken('oklch(47.642% 0.29956 274.93693)', 10); // oklch(40.377% 0.25281 275.46794)
```
**saturate(input: string, amount: number): string**
Get a color with increased saturation.
```typescript
import { saturate } from 'colorizr';
saturate('#ff0044', 10); // #ff0044 (already at the maximum)
saturate('pink', 10); // #ffc0cb
```
**desaturate(input: string, alpha: number): string**
Get a color with decreased saturation.
```typescript
import { desaturate } from 'colorizr';
desaturate('#ff0044', 10); // #f20d4a
desaturate('oklab(70.622% 0.1374 0.14283)', 10); // oklab(69.021% 0.12176 0.13721)
```
**invert(input: string): string**
Invert the color.
```typescript
import { invert } from 'colorizr';
invert('#07e'); // '#0077ee'
invert('#f058'); // '#ff005588'
```
**rotate(input: string, degrees: number): string**
Get a color with a hue rotated by the specified degrees.
```typescript
import { rotate } from 'colorizr';
rotate('#ff0044', 30); // #ff3b00
```
**opacify(input: string, alpha: number, format?: ColorType): string**
Add opacity to a color
```typescript
import { opacify } from 'colorizr';
opacify('hsl(344, 100, 50)', 0.9); // hsl(344 100 50 / 90%)
opacify('#ff0044', 0.8); // #ff0044cc
```
**transparentize(input: string, alpha: number, format?: ColorType): string**
Increase/decrease the color opacity.
```typescript
import { transparentize } from 'colorizr';
transparentize('hsl(344, 100, 50)', 10); // hsl(344 100 50 / 90%)
transparentize('#ff0044', 50, 'hsl'); // #ff004480
```
### Comparison
**brightnessDifference(left: string, right: string): number**
Get the brightness difference between the two colors.
```typescript
import { brightnessDifference } from 'colorizr';
brightnessDifference('#fff', 'rgb(255, 0, 68)'); // 171.003
```
**colorDifference(left: string, right: string): number**
Get the color difference between the two colors.
```typescript
import { colorDifference } from 'colorizr';
colorDifference('hsl(0 0% 100%)', '#f04'); // 442
```
**compare(left: string, right: string): Analysis**
Get the WCAG analysis between two colors.
```typescript
import { compare } from 'colorizr';
compare('#ff0044', '#fff');
({
"brightnessDifference": 171.003,
"colorDifference": 442,
"compliant": 1,
"contrast": 3.94,
"largeAA": true,
"largeAAA": false,
"normalAA": false,
"normalAAA": false,
})
```
**contrast(left: string, right: string): number**
Get the WCAG contrast ratio between two colors.
```typescript
import { contrast } from 'colorizr';
contrast('hsl(0 0% 100%)', 'rgb(255 0 68)'); // 3.94
```
### Generators
**palette(input: string, options?: PaletteOptions): string[]**
Generate a palette of colors.
```typescript
import { palette } from 'colorizr';
palette('#ff0044');
// ['#ff0044', '#ff7700', '#88ff00', '#00ff77', '#0088ff', '#7700ff'];
palette('#ff0044', { type: 'monochromatic' });
// ['#ff99b4', '#ff5582', '#ff1150', '#cc0036', '#880024', '#440012']
```
**scheme(input: string, type: SchemeOptions): string[]**
Get a color scheme.
```typescript
import { scheme } from 'colorizr';
const complementary = scheme('rgb(255 0 68)'); // ['#ff0044', '#00ffbb']
const triadic = scheme('#ff0044', 'triadic'); // ['#ff0044', '#44ff00', '#0044ff']
```
**swatch(input: string, options?: SwatchOptions): Swatch**
Generate a color swatch with eleven shades, from lightest (50) to darkest (950).
```typescript
import { swatch } from 'colorizr';
swatch('#ff0044');
/*
{
'50': '#ffeeed',
'100': '#ffe0df',
'200': '#ffc7c6',
'300': '#ffa7a7',
'400': '#ff8186',
'500': '#ff5464',
'600': '#f20f42',
'700': '#d40021',
'800': '#ad0000',
'900': '#7d0000',
'950': '#470000'
}
*/
swatch('#ff0044', { lightnessFactor: 1.2, maxLightness: 0.9, minLightness: 0.1 });
/*
{
'50': '#ffc6c5',
'100': '#ffaaaa',
'200': '#ff868a',
'300': '#ff5c6a',
'400': '#f8284a',
'500': '#df002d',
'600': '#c0000f',
'700': '#9b0000',
'800': '#710000',
'900': '#450000',
'950': '#180000'
}
*/
```
### Converters
The default precision is 5.
**convert(input: string, format: ColorType): string**
Convert a color string to another format.
```typescript
import { convert } from 'colorizr';
convert('#ff0044', 'hsl') // hsl(344 100% 50%)
convert('rgb(255 0 68)', 'oklch') // oklch(63.269% 0.25404 19.90218)
```
**hex2hsl(input: string): HSL**
Convert HEX to HSL.
```typescript
import { hex2hsl } from 'colorizr';
hex2hsl('#ff0044'); // { h: 344, s: 100, l: 50 }
```
**hex2oklab(input: string, precision?: number): LAB**
Convert HEX to OKLAB.
```typescript
import { hex2oklab } from 'colorizr';
hex2oklab('#ff0044'); // { l: 0.63269, a: 0.23887, b: 0.08648 }
```
**hex2oklch(input: string, precision?: number): LCH**
Convert HEX to OKLCH.
```typescript
import { hex2oklch } from 'colorizr';
hex2oklch('#ff0044'); // { l: 0.63269, c: 0.25404, h: 19.90218 }
```
**hex2rgb(input: string): RGB**
Convert HEX to RGB.
```typescript
import { hex2rgb } from 'colorizr';
hex2rgb('#ff0044'); // { r: 255, g: 0, b: 68 }
```
**hsl2hex(input: HSL | ColorTuple): string**
Convert HSL to HEX.
```typescript
import { hsl2hex } from 'colorizr';
hsl2hex({ h: 344, s: 100, l: 50 }); // '#ff0044'
hsl2hex([344, 100, 50]); // '#ff0044'
```
**hsl2oklab(input: HSL | ColorTuple, precision?: number): LAB**
Convert HSL to OKLAB.
```typescript
import { hsl2oklab } from 'colorizr';
hsl2oklab({ h: 344, s: 100, l: 50 }); // { l: 0.63269, a: 0.23887, b: 0.08648 }
hsl2oklab([344, 100, 50]); // { l: 0.63269, a: 0.23887, b: 0.08648 }
```
**hsl2oklch(input: HSL | ColorTuple, precision?: number): LCH**
Convert HSL to OKLCH.
```typescript
import { hsl2oklch } from 'colorizr';
hsl2oklch({ h: 344, s: 100, l: 50 }); // { l: 0.63269, c: 0.25404, h: 19.90218 }
hsl2oklch([344, 100, 50]); // { l: 0.63269, c: 0.25404, h: 19.90218 }
```
**hsl2rgb(input: HSL | ColorTuple): RGB**
Convert HSL to RGB.
```typescript
import { hsl2rgb } from 'colorizr';
hsl2rgb({ h: 344, s: 100, l: 50 }); // { r: 255, g: 0, b: 68 }
hsl2rgb([344, 100, 50]); // { r: 255, g: 0, b: 68 }
```
**oklab2hex(input: LAB | ColorTuple): string**
Convert OKLAB to HEX.
```typescript
import { oklab2hex } from 'colorizr';
oklab2hex({ l: 0.63269, a: 0.23887, b: 0.08648 }); // '#ff0044'
oklab2hex([0.63269, 0.23887, 0.08648]); // '#ff0044'
```
**oklab2hsl(input: LAB | ColorTuple): HSL**
Convert OKLAB to HSL.
```typescript
import { oklab2hsl } from 'colorizr';
oklab2hsl({ l: 0.63269, a: 0.23887, b: 0.08648 }); // { h: 344, s: 100, l: 50 }
oklab2hsl([0.63269, 0.23887, 0.08648]); // { h: 344, s: 100, l: 50 }
```
**oklab2oklch(input: LAB | ColorTuple, precision?: number): LCH**
Convert OKLAB to OKLCH.
```typescript
import { oklab2oklch } from 'colorizr';
oklab2oklch({ l: 0.63269, a: 0.23887, b: 0.08648 }); // { l: 0.63269, c: 0.25404, h: 19.90218 }
oklab2oklch([0.63269, 0.23887, 0.08648]); // { l: 0.63269, c: 0.25404, h: 19.90218 }
```
**oklab2rgb(input: LAB | ColorTuple, precision: number = 0): RGB**
Convert OKLAB to RGB.
```typescript
import { oklab2rgb } from 'colorizr';
oklab2rgb({ l: 0.63269, a: 0.23887, b: 0.08648 }); // { r: 255, g: 0, b: 68 }
oklab2rgb([0.63269, 0.23887, 0.08648]); // { r: 255, g: 0, b: 68 }
```
**oklch2hex(input: LCH | ColorTuple): string**
Convert OKLCH to HEX.
```typescript
import { oklch2hex } from 'colorizr';
oklch2hex({ l: 0.63269, c: 0.25404, h: 19.90218 }); // '#ff0044'
oklch2hex([0.63269, 0.25404, 19.90218]); // '#ff0044'
```
**oklch2hsl(input: LCH | ColorTuple): HSL**
Convert OKLCH to HSL.
```typescript
import { oklch2hsl } from 'colorizr';
oklch2hsl({ l: 0.63269, c: 0.25404, h: 19.90218 }); // { h: 344, s: 100, l: 50 }
oklch2hsl([0.63269, 0.25404, 19.90218]); // { h: 344, s: 100, l: 50 }
```
**oklch2oklab(input: LCH | ColorTuple, precision?: number): LAB**
Convert OKLCH to OKLAB.
```typescript
import { oklch2oklab } from 'colorizr';
oklch2oklab({ l: 0.63269, c: 0.25404, h: 19.90218 }); // { l: 0.63269, a: 0.23887, b: 0.08648 }
oklch2oklab([0.63269, 0.25404, 19.90218]); // { l: 0.63269, a: 0.23887, b: 0.08648 }
```
**oklch2rgb(input: LCH | ColorTuple, precision: number = 0): RGB**
Convert OKLCH to RGB.
```typescript
import { oklch2rgb } from 'colorizr';
oklch2rgb({ l: 0.63269, c: 0.25404, h: 19.90218 }); // { r: 255, g: 0, b: 68 }
oklch2rgb([0.63269, 0.25404, 19.90218]); // { r: 255, g: 0, b: 68 }
```
**rgb2hex(input: RGB | ColorTuple): string**
Convert RGB to HEX.
```typescript
import { rgb2hex } from 'colorizr';
rgb2hex({ r: 255, g: 0, b: 68 }); // '#ff0044'
rgb2hex([255, 0, 68]); // '#ff0044'
```
**rgb2hsl(input: RGB | ColorTuple): HSL**
Convert RGB to HSL.
```typescript
import { rgb2hsl } from 'colorizr';
rgb2hsl({ r: 255, g: 0, b: 68 }); // { h: 344, s: 100, l: 50 }
rgb2hsl([255, 0, 68]); // { h: 344, s: 100, l: 50 }
```
**rgb2oklab(input: RGB | ColorTuple, precision?: number): LAB**
Convert RGB to OKLAB.
```typescript
import { rgb2oklab } from 'colorizr';
rgb2oklab({ r: 255, g: 0, b: 68 }); // { l: 0.63269, a: 0.23887, b: 0.08648 }
rgb2oklab([255, 0, 68]); // { l: 0.63269, a: 0.23887, b: 0.08648 }
```
**rgb2oklch(input: RGB | ColorTuple, precision?: number): LCH**
Convert RGB to OKLCH.
```typescript
import { rgb2oklch } from 'colorizr';
rgb2oklch({ r: 255, g: 0, b: 68 }); // { l: 0.63269, c: 0.25404, h: 19.90218 }
rgb2oklch([255, 0, 68]); // { l: 0.63269, c: 0.25404, h: 19.90218 }
```
### Utilities
**addAlphaToHex(input: string, alpha: number): string**
Add an alpha value to a hex string
```typescript
import { addAlphaToHex } from 'colorizr';
addAlphaToHex('#ff0044', 0.9); // '#ff0044e6'
addAlphaToHex('#ff0044cc', 0.9); // '#ff0044e6'
```
**convertAlphaToHex(input: number): string**
Convert an alpha value to a hex value.
```typescript
import { convertAlphaToHex } from 'colorizr';
convertAlphaToHex(0.5); // '80'
```
**extractAlphaFromHex(input: string): number**
Extract the alpha value from a hex string
```typescript
import { extractAlphaFromHex } from 'colorizr';
convertAlphaToHex('#ff004480'); // 0.5
```
**extractColorParts(input: string): ExtractColorPartsReturn**
Extract the color parts from a CSS color string.
Hex colors are not supported.
```typescript
type ExtractColorPartsReturn = {
alpha?: number;
model: 'hsl' | 'oklab' | 'oklch' | 'rgb';
} & Record<string, number>;
extractColorParts('rgb(255 0 68)') // { model: 'rgb', r: 255, g: 0, b: 68 }
extractColorParts('hsl(344 100% 50% / 90%)') // { alpha: 0.9, model: 'hsl', h: 344, g: 100, l: 50 }
```
**formatCSS(input: HSL | RGB, options?: FormatCSSOptions): string**
Get a css string from a color object.
```typescript
import { formatCSS } from 'colorizr';
formatCSS({ h: 344, s: 100, l: 50 }, { format: 'rgb' }); // 'rgb(255, 0, 68)'
formatCSS({ r: 255, g: 0, b: 68 }, { alpha: 0.5, format: 'hsl' }); // 'hsla(344, 100%, 50%, 0.5)'
```
**formatHex(input: string): string**
Format a short hex string of 3 (or 4) digits into 6 (or 8) digits.
```typescript
import { formatHex } from 'colorizr';
formatHex('#07e'); // '#0077ee'
formatHex('#f058'); // '#ff005588'
```
**getOkLCHMaxChroma(input: string | LCH, precision?: number): number**
Get the maximum chroma for a given lightness and hue in the OkLCH color space.
```typescript
import { getOkLCHMaxChroma } from 'colorizr';
getOkLCHMaxChroma({ l: 0.63269, c: 0.25404, h: 19.90218 }); // 0.28643
getOkLCHMaxChroma('#00ff44'); // 0.30921
```
**getP3Color(input: string | LCH): string**
Get a OkLCH color in the P3 color space.
```typescript
import { getP3Color } from 'colorizr';
getP3Color({ l: 0.63269, c: 0.25404, h: 19.90218 }); // oklch(0.63269 0.28643 19.90218)
getP3Color('#00ff44'); // oklch(0.86876 0.30921 144.65534)
```
**parseCSS(input: string, format?: ColorType): string | HSL | RGB**
Parse a css string to hex, HSL, OKLAB, OKLCH, or RGB.
If the format isn't set, it will return the same format as the input.
```typescript
import { parseCSS } from 'colorizr';
parseCSS('hsl(344 100% 50%)'); // { h: 344, l: 50, s: 100 }
parseCSS('#ff0044', 'hsl'); // { h: 344, l: 50, s: 100 }
```
**random(type: ColorType = 'hex'): string**
Get a random color.
```typescript
import { random } from 'colorizr';
random(); // '#b385e0'
random('oklch') // oklab(86.876% -0.22518 0.1597)
```
**removeAlphaFromHex(input: string): string**
Remove the alpha value from a hex string
```typescript
import { removeAlphaFromHex } from 'colorizr';
removeAlphaFromHex('#ff0044cc'); // '#ff0044'
```
**textColor(input: string, options?: TextColorOptions): string**
Get a contrasting color (black or white) for the input color.
```typescript
import { textColor } from 'colorizr';
textColor('#ff0044'); // #ffffff
textColor('#fff800'); // #000000
```
### Validators
**isValidColor(input: any): boolean**
Check if the input is a valid color.
```typescript
import { isValidColor } from 'colorizr';
isValidColor('#ff0044'); // true
isValidColor('#ff004400'); // true
isValidColor('hsl(136 100% 50%)'); // true
isValidColor('hsla(344, 100%, 50%, 0.4)'); // true
isValidColor('oklab(70.622% 0.1374 0.14283)'); // true
isValidColor('oklch(47.642% 0.29956 274.93693)'); // true
isValidColor('rgb(255 230 109)'); // true
isValidColor('blue'); // true
isValidColor('aliceblue'); // true
isValidColor('#mmff00'); // false
isValidColor('blue-ish'); // false
```
**isHex(input: unknown): boolean**
Check if the input is a valid hex color.
```typescript
import { isHex } from 'colorizr';
isHex('#f04'); // true
isHex('#ff0044'); // true
isHex('#ff0044cc'); // true
```
**isHSL(input: unknown): boolean**
Check if the input is a valid HSL object.
```typescript
import { isHSL } from 'colorizr';
isHSL({ h: 344, s: 100, l: 50 }); // true
```
**isLAB(input: unknown): boolean**
Check if the input is a valid LAB color.
```typescript
import { isLAB } from 'colorizr';
isLAB({ l: 0.63269, a: 0.23887, b: 0.08648 }); // true
```
**isLHC(input: unknown): boolean**
Check if the input is a valid LCH color.
```typescript
import { isLHC } from 'colorizr';
isLHC({ l: 0.63269, c: 0.25404, h: 19.90218 }); // true
```
**isRGB(input: unknown): boolean**
Check if the input is a valid RGB color.
```typescript
import { isRGB } from 'colorizr';
isRGB({ r: 255, g: 0, b: 68 }); // true
```
### Class
```typescript
import Colorizr from 'Colorizr';
const colorizr = new Colorizr('#ff0044');
colorizr.hex; // #ff0044
colorizr.hsl; // { h: 344, s: 100, l: 50 };
colorizr.rgb; // { r: 255, g: 0, b: 68 };
```
#### Getters
**colorizr.hex**
Get the hex code.
**colorizr.hsl**
Get the HSL object.
**colorizr.oklab**
Get the OKLAB object.
**colorizr.oklch**
Get the OKLCH object.
**colorizr.rgb**
Get the RGB object.
**colorizr.hue**
Get the hue (0-360).
**colorizr.saturation**
Get the saturation (0-100).
**colorizr.lightness**
Get the lightness (0-100).
**colorizr.red**
Get the red level (0-255).
**colorizr.green**
Get the green level (0-255).
**colorizr.blue**
Get the blue level (0-255).
**colorizr.chroma**
Get the chroma (0-1).
**colorizr.luminance**
Get the luminance (0-1).
**colorizr.opacity**
Get the opacity (0-1).
**colorizr.css**
Get the css string of the same type as the input.
**colorizr.textColor**
Get a contrasting color (black or white).
#### Methods
**colorizr.format(type: ColorType, precision?: number)**
Returns the formatted color with the type
...
Also, all the [manipulators](#Manipulators) and [comparison](#Comparison) utilities.
## Credits / References
[color.js](https://github.com/color-js/color.js)
[chroma-js](https://gka.github.io/chroma.js/)
[calculating-color-contrast](https://24ways.org/2010/calculating-color-contrast/)
[Colour Contrast Check](https://snook.ca/technical/colour_contrast/colour.html)
[Contrast Checker](https://webaim.org/resources/contrastchecker/)
[Converting Color Spaces in typescript](https://css-tricks.com/converting-color-spaces-in-typescript/)
[A perceptual color space for image processing](https://bottosson.github.io/posts/oklab/)