npm package: @hairy/palette
Description: Library for color palette
Author: Hairyf
Latest version: 1.51.0

# @hairy/palette

<!-- automd:badges name="@hairy/palette" github="hairyf/hairylib" license bundlephobia -->

[![npm version](https://img.shields.io/npm/v/@hairy/palette)](https://npmjs.com/package/@hairy/palette)
[![npm downloads](https://img.shields.io/npm/dm/@hairy/palette)](https://npm.chart.dev/@hairy/palette)
[![bundle size](https://img.shields.io/bundlephobia/minzip/@hairy/palette)](https://bundlephobia.com/package/@hairy/palette)
[![license](https://img.shields.io/github/license/hairyf/hairylib)](https://github.com/hairyf/hairylib/blob/main/LICENSE)

<!-- /automd -->

Color palette utilities for generating and working with theme colors.

## Install

<!-- automd:pm-install name="@hairy/palette" -->

```sh
# ✨ Auto-detect
npx nypm install @hairy/palette

# npm
npm install @hairy/palette

# yarn
yarn add @hairy/palette

# pnpm
pnpm add @hairy/palette

# bun
bun install @hairy/palette

# deno
deno install npm:@hairy/palette
```

<!-- /automd -->

## API

<!-- automd:jsdocs src="./src/index.ts" -->

### `blend(fgColor, bgColor)`

Calculates the [blend](https://www.w3.org/TR/compositing-1/#simplealphacompositing) of two colors.

Accepts a HEX/A String or a RGB/A Object as `fgColor`/`bgColor`. If the alpha channel of the `fgColor` is completely opaque, then the result will be the `fgColor`. If the alpha channel of the `bgColor` is completely opaque, then the resulting blended color will also be opaque. Returns the same type as input for fgColor.

### `brightness(color)`

Calculates the [color contrast](https://www.w3.org/TR/AERT/#color-contrast) of the `color`.

Accepts a HEX/A String, a RGB/A String or a RGB/A Object as `color`. Returns a value between 0 and 1.

### `changeAlpha(color, alpha)`

Change color transparency

### `colorPalette(color, index)`

Obtain palette colors based on color (from left to right, from light to dark, with 6 as the main color number)

### `hexToRgb(hex)`

Converts a HEX/A color

String (`#RRGGBB<AA>`) or a RGB/A color String(`rgb(R, G, B<, A>)`)

to its RGB/A representation as an

Object (`{ r: [0-255], g: [0-255], b: [0-255}<, a: [0-100]>}`).

If Alpha channel is present in the original object it will be present also in the output.

### `hsvToRgb()`

Converts a HEX/A color

String (`#RRGGBB<AA>`)

to its RGB/A representation as an

Object (`{ r: [0-255], g: [0-255], b: [0-255}<, a: [0-100]>}`) .

If Alpha channel is present in the original object it will be present also in the output.

### `lighten(color, percent)`

Lighten the `color` (if `percent` is positive) or darken it (if `percent` is negative).

Accepts a HEX/A String or a RGB/A String as color and a percent (0 to 1 or -1 to 0) of lighten/darken to be applied to the   `color`. Returns a HEX String representation of the calculated `color`.

### `luminance(color)`

Calculates the [relative luminance](https://www.w3.org/TR/WCAG20/#relativeluminancedef) of the `color`.

Accepts a HEX/A String, a RGB/A String or a RGB/A Object as `color`. Returns a value between 0 and 1.

### `rgbToHex()`

Converts a RGB/A color

Object (`{ r: [0-255], g: [0-255], b: [0-255}<, a: [0-100]>}`)

to its HEX/A representation as a

String (`#RRGGBB<AA>`).

If Alpha channel is present in the original object it will be present also in the output.

### `rgbToHsv()`

Converts a RGB/A color

Object (`{ r: [0-255], g: [0-255], b: [0-255}<, a: [0-100]>}`)

to its HSV/A representation as an

Object (`{ h: [0-360], s: [0-100], v: [0-100}, a: [0-1]}`).

If Alpha channel is present in the original object it will be present also in the output.

### `textToRgb(str)`

Converts a HEX/A color

String (`#RRGGBB<AA>`) or a RGB/A color String(`rgb(R, G, B<, A>)`)

to its RGB/A representation as an

Object (`{ r: [0-255], g: [0-255], b: [0-255}<, a: [0-100]>}`).

If Alpha channel is present in the original object it will be present also in the output.

<!-- /automd -->

## Directory structure

<!-- automd:dir-tree imports=""maxDepth=2 -->

```
├── src/
│   └── index.ts
├── test/
│   └── index.test.ts
├── package.json
├── README.md
└── tsdown.config.ts
```

<!-- /automd -->

## Source

<!-- automd:file src="./src/index.ts" code lang="ts" -->

```ts [index.ts]
import type { AnyColor, HsvaColor, RgbaColor } from 'colord'
import { colord, extend } from 'colord'
import a11yPlugin from 'colord/plugins/a11y'
import mixPlugin from 'colord/plugins/mix'

extend([a11yPlugin, mixPlugin])

export type RGBA = Record<'r' | 'g' | 'b' | 'a', number>
export type RGB = Record<'r' | 'g' | 'b', number> & { a?: number }
export type HexColor = string
export type HSVA = Record<'h' | 's' | 'v' | 'a', number>

export type RGBA_TEXT = string
export type HEX_TEXT = string
export type HSVA_TEXT = string
export type COLOR = RGBA_TEXT | HEX_TEXT | HSVA_TEXT
export type PALETTE_INDEXES = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10

/**
 * Converts a RGB/A color
 *
 * Object (`{ r: [0-255], g: [0-255], b: [0-255}<, a: [0-100]>}`)
 *
 * to its HEX/A representation as a
 *
 * String (`#RRGGBB<AA>`).
 *
 * If Alpha channel is present in the original object it will be present also in the output.
 */
export function rgbToHex({ r, g, b, a }: RgbaColor): HexColor {
  return colord({ r, g, b, a }).toHex()
}

/**
 * Converts a HEX/A color
 *
 * String (`#RRGGBB<AA>`) or a RGB/A color String(`rgb(R, G, B<, A>)`)
 *
 * to its RGB/A representation as an
 *
 * Object (`{ r: [0-255], g: [0-255], b: [0-255}<, a: [0-100]>}`).
 *
 * If Alpha channel is present in the original object it will be present also in the output.
 */
export function hexToRgb(hex: HexColor): RgbaColor {
  return colord(hex).toRgb()
}

/**
 * Converts a HEX/A color
 *
 * String (`#RRGGBB<AA>`)
 *
 * to its RGB/A representation as an
 *
 * Object (`{ r: [0-255], g: [0-255], b: [0-255}<, a: [0-100]>}`) .
 *
 * If Alpha channel is present in the original object it will be present also in the output.
 */
export function hsvToRgb({ h, s, v, a }: HsvaColor): RgbaColor {
  return colord({ h, s, v, a }).toRgb()
}

/**
 * Converts a RGB/A color
 *
 * Object (`{ r: [0-255], g: [0-255], b: [0-255}<, a: [0-100]>}`)
 *
 * to its HSV/A representation as an
 *
 * Object (`{ h: [0-360], s: [0-100], v: [0-100}, a: [0-1]}`).
 *
 * If Alpha channel is present in the original object it will be present also in the output.
 */
export function rgbToHsv({ r, g, b, a }: RgbaColor): HsvaColor {
  return colord({ r, b, g, a }).toHsv()
}

/**
 * Converts a HEX/A color
 *
 * String (`#RRGGBB<AA>`) or a RGB/A color String(`rgb(R, G, B<, A>)`)
 *
 * to its RGB/A representation as an
 *
 * Object (`{ r: [0-255], g: [0-255], b: [0-255}<, a: [0-100]>}`).
 *
 * If Alpha channel is present in the original object it will be present also in the output.
 */
export function textToRgb(str: AnyColor): RgbaColor {
  return colord(str).toRgb()
}

/**
 * Lighten the `color` (if `percent` is positive) or darken it (if `percent` is negative).
 *
 * Accepts a HEX/A String or a RGB/A String as color and a percent (0 to 1 or -1 to 0) of lighten/darken to be applied to the   `color`. Returns a HEX String representation of the calculated `color`.
 */
export function lighten(color: AnyColor, percent: number) {
  return colord(color).lighten(percent).toHex()
}
/**
 * Calculates the [relative luminance](https://www.w3.org/TR/WCAG20/#relativeluminancedef) of the `color`.
 *
 * Accepts a HEX/A String, a RGB/A String or a RGB/A Object as `color`. Returns a value between 0 and 1.
 */
export function luminance(color: AnyColor) {
  return colord(color).luminance()
}
/**
 * Calculates the [color contrast](https://www.w3.org/TR/AERT/#color-contrast) of the `color`.
 *
 * Accepts a HEX/A String, a RGB/A String or a RGB/A Object as `color`. Returns a value between 0 and 1.
 */
export function brightness(color: AnyColor) {
  return colord(color).brightness()
}

/**
 * Calculates the [blend](https://www.w3.org/TR/compositing-1/#simplealphacompositing) of two colors.
 *
 * Accepts a HEX/A String or a RGB/A Object as `fgColor`/`bgColor`. If the alpha channel of the `fgColor` is completely opaque, then the result will be the `fgColor`. If the alpha channel of the `bgColor` is completely opaque, then the resulting blended color will also be opaque. Returns the same type as input for fgColor.
 */
export function blend(fgColor: AnyColor, bgColor: AnyColor) {
  return colord(fgColor).mix(bgColor)
}

/**
 * Change color transparency
 */
export function changeAlpha(color: COLOR, alpha: number) {
  return colord(color).alpha(alpha).toHex()
}

const hueStep = 2
const saturationStep = 16
const saturationStep2 = 5
const brightnessStep1 = 5
const brightnessStep2 = 15
const lightColorCount = 5
const darkColorCount = 4

/**
 * Obtain palette colors based on color (from left to right, from light to dark, with 6 as the main color number)
 * @param color - Color
 * @param index - The corresponding color number of the color palette (6 as the main color number)
 * @description algorithm implementation draws inspiration from ant design palette algorithm https://github.com/ant-design/ant-design/blob/master/components/style/color/colorPalette.less
 */
export function colorPalette(color: string | RgbaColor, index: PALETTE_INDEXES) {
  if (typeof color !== 'string' && (!color || color.r === void 0))
    throw new TypeError('Expected a string or a {r, g, b} object as color')

  const rgb = typeof color === 'string' ? textToRgb(color) : color
  const oldHsv = colord(rgb).toHsv()

  if (index === 6)
    return rgbToHex(rgb)

  const light = index < 6
  const i = light ? lightColorCount + 1 - index : index - lightColorCount - 1
  const newHsv = {
    h: hue(oldHsv, i, light),
    s: saturation(oldHsv, i, light),
    v: value(oldHsv, i, light),
    a: oldHsv.a,
  }
  return colord(newHsv).toHex()
}

/**
 * Obtain color gradient
 * @param hsv - Color values in HSV format
 * @param i - relative distance to 6
 * @param isLight - Is it a bright color
 */
function hue(hsv: HsvaColor, i: number, isLight: boolean) {
  let hue: number
  if (hsv.h >= 60 && hsv.h <= 240) {
    // Cool color tone
    // Dimming and brightening colors, clockwise rotation brings warmth
    // Deepen and darken the color, rotate counterclockwise to make it colder
    hue = isLight ? hsv.h - hueStep * i : hsv.h + hueStep * i
  }
  else {
    // Warm color tone
    // Dimming and brightening colors are warmer when rotated counterclockwise
    // Deepen and darken, rotate clockwise to make it cooler
    hue = isLight ? hsv.h + hueStep * i : hsv.h - hueStep * i
  }
  if (hue < 0)
    hue += 360
  else if (hue >= 360)
    hue -= 360

  return hue
}

/**
 * Obtain saturation gradient
 * @param hsv - Color values in HSV format
 * @param i - relative distance to 6
 * @param isLight - Is it a bright color
 */
function saturation(hsv: HsvaColor, i: number, isLight: boolean) {
  let saturation: number
  if (isLight)
    saturation = hsv.s - saturationStep * i
  else if (i === darkColorCount)
    saturation = hsv.s + saturationStep
  else saturation = hsv.s + saturationStep2 * i

  if (saturation > 100)
    saturation = 100

  if (isLight && i === lightColorCount && saturation > 10)
    saturation = 10

  if (saturation < 6)
    saturation = 6

  return saturation
}

/**
 * Obtain brightness gradient
 * @param hsv - Color values in HSV format
 * @param i - relative distance to 6
 * @param isLight - Is it a bright color
 */
function value(hsv: HsvaColor, i: number, isLight: boolean) {
  let value: number
  value = isLight ? hsv.v + brightnessStep1 * i : hsv.v - brightnessStep2 * i

  if (value > 100)
    value = 100

  return value
}
```

<!-- /automd -->

## Contributors

<!-- automd:contributors github="hairyf/hairylib" author="Hairyf" license="MIT" -->

Published under the [MIT](https://github.com/hairyf/hairylib/blob/main/LICENSE) license.
Made by [@Hairyf](https://github.com/Hairyf) and [community](https://github.com/hairyf/hairylib/graphs/contributors) 💛
<br><br>
<a href="https://github.com/hairyf/hairylib/graphs/contributors">
<img src="https://contrib.rocks/image?repo=hairyf/hairylib" />
</a>

<!-- /automd -->

## License

<!-- automd:fetch url="gh:hairyf/hairylib/main/LICENSE" -->

MIT License

Copyright (c) 2025-PRESENT Hairyf <https://github.com/hairyf>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

<!-- /automd -->

<!-- automd:with-automd -->

---

_🤖 auto updated with [automd](https://automd.unjs.io)_

<!-- /automd -->