# @oncehub/relative-luminance

> Relative luminance formula

Latest version **2.1.6** (published 2026-02-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install @oncehub/relative-luminance
pnpm add @oncehub/relative-luminance
yarn add @oncehub/relative-luminance
bun add @oncehub/relative-luminance
```

## Health

**Score 70/100 (B)** — status: stable.

Positive: has types; esm support; no vulnerabilities; has provenance; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.1.6 |
| Published | 2026-02-27 |
| First published | 2023-07-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 13.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 0 |
| Maintainers | oncehub.admin |
| Keywords | luminance, colors, accessibility |

## Links

- npm: https://www.npmjs.com/package/@oncehub/relative-luminance
- Repository: https://github.com/scheduleonce/relative-luminance
- Homepage: https://github.com/scheduleonce/relative-luminance#readme
- Issues: https://github.com/scheduleonce/relative-luminance/issues
- npm.io page: https://npm.io/package/@oncehub/relative-luminance

## 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

- 2.1.6 (latest) — 2026-02-27
- 2.1.4 — 2025-09-29
- 2.1.4-beta.1 — 2025-09-15
- 2.1.3 — 2025-05-09
- 2.1.3-beta — 2025-05-08
- 2.1.0 — 2023-07-07
- 2.0.1 — 2023-07-04
- 2.0.0 — 2023-07-04
- 1.0.0 — 2023-07-04

## README

# relative-luminance

[![Build status](https://github.com/scheduleonce/relative-luminance/actions/workflows/node.js.yml/badge.svg)](https://github.com/scheduleonce/relative-luminance/actions) [![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)

> Calculate the luminance of a given hex color code

[Relative luminance](https://www.w3.org/WAI/GL/wiki/Relative_luminance) is a measure of the brightness of a color that is useful in determining the contrast between two colors. For example, if you want to apply a background color to a button, you would want to calculate the luminance of the color to ensure that the text on the button is readable. If the background color is too light, you would not want to put light text on it, and vice versa. This is especially important for accessibility reasons, as it ensures that people with visual impairments can read the text on your buttons and other UI elements.

### Installation

To install this module, run the following command:

```sh
$ npm install @oncehub/relative-luminance
```

### Usage

To use this module, simply require it in your Node.js application and call the relativeLuminance function with a hex color code as its argument. The function will return either "dark" or "light" depending on the luminance of the color.

```js
import luminance from "@oncehub/relative-luminance";
console.log(luminance("#000000")); // "dark"
console.log(luminance("#ffffff")); // "light"
```

If the input is invalid, the function will throw either "Please provide a hex color code" or "Please provide a valid hex code".

```js
console.log(luminance()); // "Please provide a hex color code"
console.log(luminance("#12345")); // "Please provide a valid hex code"
```

### Development

1. Storybook is [automatically deployed](.github/workflows/deploy.yml) to Github Pages when pushing to main.
2. Package is automatically pushed to npm when [creating a new release](.github/workflows/npm-publish.yml) on Github. Check out the release section in the repo. Read more about releases [here](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository).

### License

This module is licensed under the MIT License. See the LICENSE file for details.

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