# color2k > Small, zero-dependency JavaScript color manipulation and WCAG contrast library with TypeScript types - Install with `npm i color2k`. Use named imports: `import { darken, toHex } from 'color2k'`. There is no default export and no chaining. - Colors go in as CSS strings, and functions that produce a color return a CSS string. Inputs can be hex (3, 4, 6 or 8 digits), comma-separated `rgb()`, `rgba()`, `hsl()` or `hsla()`, a named color, or `transparent`. - Amounts are decimals from 0 to 1 and are absolute. `darken(color, 0.1)` lowers lightness by 10 percentage points. It is not a 10% relative change. - `darken`, `lighten`, `saturate`, `desaturate` and `adjustHue` return `hsla()` strings. `transparentize`, `opacify` and `mix` return `rgba()` strings, and so does the function `getScale` gives you. Wrap a result in `toHex` when you need hex. - `mix(color1, color2, weight)`: weight 0 gives `color1` and weight 1 gives `color2`, always as an `rgba()` string. - `getScale('red', 'yellow', 'green')` takes colors as separate arguments, not an array, and returns a function, not a color: call it with a number from 0 to 1. - `readableColor(background)` returns `'#000'` or `'#fff'`. `hasBadContrast(color, standard = 'aa', background = '#fff')` returns `true` when contrast is too low. - A string color2k can't parse throws a `ColorError`. Space-separated `rgb(0 0 0 / 50%)`, percentage alpha, `oklch()`, `lab()` and `color()` are not supported. - Parsing is loose and is not validation: `rgb(999, 0, 0)` is accepted as written and not clamped, and about 3% of made-up color names parse as some color. Validate user input yourself before passing it in (`CSS.supports` is not equivalent: it accepts forms color2k rejects). - `getContrast`, `hasBadContrast` and `readableColor` ignore alpha. Flatten a see-through color onto its background before measuring. - `adjustHue` does not wrap hues below 0. If the color's hue plus the degrees is negative (`adjustHue('red', -120)`), the result is `hsla(-120, ...)`, which color2k throws on if you pass it back in (a known bug). Add 360 to a negative angle to avoid it. - sRGB only. There are no CMYK, LAB or wide-gamut conversions. ## Docs - [Full documentation](https://color2k.com/llms-full.txt): quickstart, the complete API, supported colors and recipes in one Markdown file - [Quickstart](https://color2k.com/quickstart.md): install, first calls, use without a bundler, browser and Node support - [Themes](https://color2k.com/themes.md): three theme builders that turn one color into fourteen tokens, for light or dark - [Recipes](https://color2k.com/recipes.md): hover states, readable text, contrast checks, scales and palettes - [Supported colors](https://color2k.com/supported-colors.md): what the parser reads, what each function returns, and known edges - [Size](https://color2k.com/size.md): what each import costs, other libraries, and moving from TinyColor or Polished - [Project](https://color2k.com/project.md): credits, contributing, and how releases are published - [Website](https://color2k.com/): the same documentation as one HTML page, with a live demo of every function ## API: Parse - [parseToRgba(color)](https://color2k.com/parse.md): `function parseToRgba(color: string): [number, number, number, number]`. Parses a color into red, green, blue, and alpha channel values. - [parseToHsla(color)](https://color2k.com/parse.md): `function parseToHsla(color: string): [number, number, number, number]`. Parses a color into hue, saturation, lightness, and alpha channel values. ## API: Convert - [toHex(color)](https://color2k.com/convert.md): `function toHex(color: string): string`. Converts a color to a hex color string. - [toRgba(color)](https://color2k.com/convert.md): `function toRgba(color: string): string`. Converts a color to an `rgba` color string. - [toHsla(color)](https://color2k.com/convert.md): `function toHsla(color: string): string`. Converts a color to an `hsla` color string. - [rgba(red, green, blue, alpha)](https://color2k.com/convert.md): `function rgba(red: number, green: number, blue: number, alpha: number): string`. Builds an `rgba` color string from red, green, blue, and alpha channel values. - [hsla(hue, saturation, lightness, alpha)](https://color2k.com/convert.md): `function hsla(hue: number, saturation: number, lightness: number, alpha: number): string`. Builds an `hsla` color string from hue, saturation, lightness, and alpha channel values. ## API: Adjust - [darken(color, amount)](https://color2k.com/adjust.md): `function darken(color: string, amount: number): string`. Darkens a color by subtracting from the lightness channel in HSL space. - [lighten(color, amount)](https://color2k.com/adjust.md): `function lighten(color: string, amount: number): string`. Lightens a color by adding to the lightness channel in HSL space. - [saturate(color, amount)](https://color2k.com/adjust.md): `function saturate(color: string, amount: number): string`. Saturates a color by adding to the saturation channel in HSL space. - [desaturate(color, amount)](https://color2k.com/adjust.md): `function desaturate(color: string, amount: number): string`. Desaturates a color by subtracting from the saturation channel in HSL space. - [adjustHue(color, degrees)](https://color2k.com/adjust.md): `function adjustHue(color: string, degrees: number): string`. Rotates a color's hue by the given number of degrees and returns the result as an `hsla` string. - [complement(color)](https://color2k.com/adjust.md): `function complement(color: string): string`. Rotates a color's hue by 180 degrees and returns the result as an `hsla` string, like Sass's `complement`. - [invert(color, weight)](https://color2k.com/adjust.md): `function invert(color: string, weight: number = 1): string`. Inverts a color's red, green, and blue channels, keeping its alpha, and returns the result as an `rgba` string. - [opacify(color, amount)](https://color2k.com/adjust.md): `function opacify(color: string, amount: number): string`. Makes a color more opaque by increasing the alpha channel. - [transparentize(color, amount)](https://color2k.com/adjust.md): `function transparentize(color: string, amount: number): string`. Makes a color more transparent by decreasing the alpha channel. ## API: Mix - [mix(color1, color2, weight)](https://color2k.com/mix.md): `function mix(color1: string, color2: string, weight: number): string`. Mixes two colors together using the Sass mix algorithm and returns an `rgba` color string. - [getScale(...colors)](https://color2k.com/mix.md): `function getScale(...colors: string[]): (n: number) => string`. Returns a scale function that interpolates through a list of colors. ## API: Contrast - [getContrast(color1, color2)](https://color2k.com/contrast.md): `function getContrast(color1: string, color2: string): number`. Returns the contrast ratio between two colors based on the WCAG contrast ratio formula. - [getLuminance(color)](https://color2k.com/contrast.md): `function getLuminance(color: string): number`. Returns the relative luminance of a color using the WCAG formula. - [hasBadContrast(color, standard, background)](https://color2k.com/contrast.md): `function hasBadContrast(color: string, standard: 'decorative' | 'readable' | 'aa' | 'aaa' = 'aa', background: string = '#fff'): boolean`. Returns whether a color fails a contrast threshold against a background. - [readableColor(color)](https://color2k.com/contrast.md): `function readableColor(color: string): string`. Returns black or white, whichever has better contrast against the given color. - [readableColorIsBlack(color)](https://color2k.com/contrast.md): `function readableColorIsBlack(color: string): boolean`. Returns whether black is the more readable color to place on top of the input color. ## API: Utilities - [guard(low, high, value)](https://color2k.com/utilities.md): `function guard(low: number, high: number, value: number): number`. Clamps a number between a lower and upper bound. - [ColorError](https://color2k.com/utilities.md): `class ColorError extends Error`. Error thrown when color2k cannot parse an input color. ## Optional - [Source code](https://github.com/ricokahler/color2k): one small TypeScript file per function in `src/` - [README](https://github.com/ricokahler/color2k/blob/main/README.md): the source of all of the above - [AGENTS.md](https://github.com/ricokahler/color2k/blob/main/AGENTS.md): rules for coding agents working on color2k itself - [npm package](https://www.npmjs.com/package/color2k): versions and provenance - [Releases](https://github.com/ricokahler/color2k/releases): changelog - [Contributing](https://github.com/ricokahler/color2k/blob/main/CONTRIBUTING.md): how to work on color2k