README.md

values.js

Get tints and shades of a CSS color

The lightness or darkness of a color is called its value. Tints are light values that are made by mixing a color with white, which increases lightness. Shades are dark values that are made by mixing a color with black, which reduces lightness.

https://noeldelgado.github.io/values.js/

Supports

• <color value>
  • Hexadecimal RGB value: #RGB #RRGGBB
  • #RGBA #RRGGBBAA (4 and 8-digit hexadecimal RGBA notation)
  • RGB/A - CSS Color Module Level 3 and 4 (number, percentage)
  • HSL/A - CSS Color Module Level 3 and 4 (number, deg, rad, turn)
• <color keyword>
  • One of the pre-defined color keywords.
• transparent
  • Shorthand for transparent black, rgba(0,0,0,0).

Installation

NPM

npm install values.js --save

Or as a <script> tag from a CDN as Values:

Unpkg CDN

<script src="https://unpkg.com/values.js"></script>

jsDelivr CDN

<script src="https://cdn.jsdelivr.net/npm/values.js"></script>

Usage

import Values from 'values.js'
const color = new Values('hsl(204deg 100% 50% / 1)'), { log } = console

log(color.tint(25))
//> { rgb: [64, 179, 255], alpha: 1, type: "tint", weight: 25, ...methods }
log(color.shade(12))
//> { rgb: [0, 135, 224], alpha: 1, type: "shade", weight: 12, ...methods }
log(color.tints(8))
//> (12) [Values...]
log(color.shades(23))
//> (4) [Values...]
log(color.all(20))
//> (11) [Values...]

// instance example for 'red'
Values {
  alpha: 1
  rgb: (3) [255, 0, 0]
  type: "base"
  weight: 0
  get hex: ƒ(...)
  setColor: ƒ setColor(color)
  tint: ƒ tint(weight=50)
  tints: ƒ tints(weight=10)
  shade: ƒ shade(weight=50)
  shades: ƒ shades(weight=10)
  all: ƒ all(weight=10)
  hexString: ƒ hexString()
  rgbString: ƒ rgbString()
  getBrightness: ƒ getBrightness()
}

See tests for more cases.

API

constructor(color)

Throws if the color is not accepted.

• @param {string} color — a valid CSS color string

setColor(color)

Sets a new base color, returns null if color has not been accepted.

• @param {string} color - a valid CSS color string
• @return {Values|null}

tint([weight=50])

Lightens the base color by mixing it with white as specified by weight.

• @param {number} [weight=50]
• @return {Values}

shade([weight=50)

Darkens the base color by mixing it with black as specified by weight.

• @param {number} [weight=50]
• @return {Values}

tints([weight=10])

Generates the tints of the base color as specified by weight.

• @param {number} [weight=10]
• @return {Array<Values>}

shades([percentage=10])

Generates the shades of the base color as specified by weight.

• @param {number} [weight=10]
• @return {Array<Values>}

all([weight=10])

Generates the tints and shades of the base color as specified by weight.

• @param {number} [weight=10]
• @return {Array<Values>}

hexString()

Returns the color in hexadecimal RGB notation.

• @returns {string} @example #000000 or #00000080

rgbString()

Returns the color in rgb() functional notation.

• @returns {string} @example rgb(0, 0, 0) or rgba(0, 0, 0, 0.5)

getBrightness()

Calculates the brightness of the color.

• @return {number} — the base-color brightness.

Dev

npm install 	# install dev-dependencies
npm test		# run the tests
npm run dev 	# watch for changes and run tests

Related

• shadowlord - Tints and shades generator tool
• mix-css-color - Mix two CSS colors together in variable proportion. Opacity is included in the calculations.
• parse-css-color - Parse a CSS color string

License

MIT © Noel Delgado