# hsluv

> Human-friendly HSL

Latest version **1.0.2** (published 2026-06-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install hsluv
pnpm add hsluv
yarn add hsluv
bun add hsluv
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2026-06-14 |
| First published | 2016-12-15 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 30.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 36 |
| Author | Alexei Boronine |
| Maintainers | boronine, hsluvcontributors |
| Keywords | color, color space, CIE, RGB, HSL, HSLuv, HPLuv |

## Links

- npm: https://www.npmjs.com/package/hsluv
- Repository: https://github.com/hsluv/hsluv-javascript
- Homepage: https://www.hsluv.org
- Issues: https://github.com/hsluv/hsluv-javascript/issues
- npm.io page: https://npm.io/package/hsluv

## Alternatives

- [postcss-color-hex-alpha](https://npm.io/package/postcss-color-hex-alpha.md) — 6.4M weekly downloads
- [randomcolor](https://npm.io/package/randomcolor.md) — 348.0K weekly downloads
- [bows](https://npm.io/package/bows.md) — 1.3K weekly downloads
- [ep_prefer_color_scheme](https://npm.io/package/ep_prefer_color_scheme.md) — 260 weekly downloads
- [coc-yank](https://npm.io/package/coc-yank.md) — 61 weekly downloads

## Recent versions

- 1.0.2 (latest) — 2026-06-14
- 1.0.2-beta.0 (beta) — 2026-06-14
- 1.0.1-rc1 (rc) — 2023-07-26
- 1.0.1 — 2023-07-27
- 1.0.0 — 2022-09-21
- 1.0.0-rc3 — 2022-09-15
- 1.0.0-rc2 — 2022-07-04
- 1.0.0-rc1 — 2022-07-03
- 0.1.0 — 2020-01-15
- 0.1.0-rc2 — 2020-01-15
- 0.1.0-rc1 — 2020-01-15
- 0.0.3 — 2018-03-05
- 0.0.2 — 2018-02-09
- 0.0.1 — 2016-12-15

## README

# HSLuv - Human-friendly HSL

[![CI](https://github.com/hsluv/hsluv-javascript/actions/workflows/nodeci.yml/badge.svg)](https://github.com/hsluv/hsluv-javascript/actions/workflows/nodeci.yml)
[![npm](https://img.shields.io/npm/v/hsluv)](https://www.npmjs.com/package/hsluv)

## Installation

Install from NPM package repository:

```bash
npm install hsluv
```

ES modules:

```javascript
import {Hsluv} from "hsluv";
```

CommonJS:

```javascript
const {Hsluv} = require("hsluv");
```

HTML include:

- Download [the latest hsluv.min.js](https://github.com/hsluv/hsluv-javascript/releases)
- Add `<script src="hsluv-x.x.x.min.js"></script>` to your HTML
- Access it via the global `window.Hsluv`

## Usage

The API is designed to avoid heap allocation. The `HSLuv` class defines the following public fields:

- RGB: `hex:String`, `rgb_r:Float` [0;1], `rgb_g:Float` [0;1], `rgb_r:Float` [0;1]
- CIE XYZ: `xyz_x:Float`, `xyz_y:Float`, `xyz_z:Float`
- CIE LUV: `luv_l:Float`, `luv_u:Float`, `luv_v:Float`
- CIE LUV LCh: `lch_l:Float`, `lch_c:Float`, `lch_h:Float`
- HSLuv: `hsluv_h:Float` [0;360], `hsluv_s:Float` [0;100], `hsluv_l:Float` [0;100]
- HPLuv: `hpluv_h:Float` [0;360], `hpluv_p:Float` [0;100], `hpluv_l:Float` [0;100]

To convert between color spaces, simply set the properties of the source color space, run the
conversion methods, then read the properties of the target color space.

Use the following methods to convert to and from RGB:

- HSLuv: `hsluvToRgb()`, `hsluvToHex()`, `rgbToHsluv()`, `hexToHsluv()`
- HPLuv: `hpluvToRgb()`, `hpluvToHex()`, `rgbToHpluv()`, `hexToHpluv()`

Use the following methods to do step-by-step conversion:

- Forward: `hsluvToLch()` (or `hpluvToLch()`), `lchToLuv()`, `luvToXyz()`, `xyzToRgb()`, `rgbToHex()`
- Backward: `hexToRgb()`, `rgbToXyz()`, `xyzToLuv()`, `luvToLch()`, `lchToHsluv()` (or `lchToHpluv()`)

For advanced usage, we also export the [bounding lines](https://www.hsluv.org/math/) in slope-intercept
format, two for each RGB channel representing the limit of the gamut.

- R < 0: `r0s`, `r0i`
- R > 1: `r1s`, `r1i`
- G < 0: `g0s`, `g0i`
- G > 1: `g1s`, `g1i`
- B < 0: `b0s`, `b0i`
- B > 1: `b1s`, `b1i`

Example:

```javascript
var conv = new Hsluv();
conv.hsluv_h = 10;
conv.hsluv_s = 75;
conv.hsluv_l = 65;
conv.hsluvToHex();
console.log(conv.hex); // Will print "#ec7d82"
```

Also available for [Stylus](http://stylus-lang.com/). See [here](https://github.com/hsluv/hsluv-stylus).

## Development

Our [Node.js CI workflow](https://github.com/hsluv/hsluv-javascript/blob/main/.github/workflows/nodeci.yml)
will build and test every push and PR to the `main` branch.

To publish a release, configure npm trusted publishing for the `hsluv/hsluv-javascript` repository and
`npm-publish.yml` workflow, then create a GitHub Release. The release tag must match the version in
`package.json`. The [Publish to npm workflow](https://github.com/hsluv/hsluv-javascript/blob/main/.github/workflows/npm-publish.yml)
will build the package and publish it to npm with provenance. Prerelease versions (for example `1.2.3-rc.1`)
are automatically published with the matching npm dist-tag.

## Changelog

### 1.0.1

- Fix TypeScript d.ts resolution for certain configurations.

### 1.0.0

- New API to avoid heap allocation.
- Transpiled from [hsluv-haxe](https://github.com/hsluv/hsluv-haxe) and converted manually to TypeScript.
- New GitHub Actions CI for build, test and publishing automation.

### 0.1.0

- Provide Typescript definitions in the NPM package.

### 0.0.3

- Expose intermediate functions in the public API.

### 0.0.2

- Improve packaging and minification.

### 0.0.1

- Initial release under the name HSLuv. Old releases can be found [here](https://www.npmjs.com/package/husl).

---
_Source: https://npm.io/package/hsluv · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._