# ts-color-class

> JavaScript Color class that manipulates colors and converts them to CSS-compatible hex or rgba strings

Latest version **0.10.1** (published 2021-04-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install ts-color-class
pnpm add ts-color-class
yarn add ts-color-class
bun add ts-color-class
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.10.1 |
| Published | 2021-04-01 |
| First published | 2020-07-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 1.2 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Dan Steinman |
| Maintainers | dsteinman |

## Links

- npm: https://www.npmjs.com/package/ts-color-class
- Repository: https://github.com/dsteinman/ts-color-class
- Homepage: https://github.com/dsteinman/ts-color-class#readme
- Issues: https://github.com/dsteinman/ts-color-class/issues
- npm.io page: https://npm.io/package/ts-color-class

## Recent versions

- 0.10.1 (latest) — 2021-04-01
- 0.10.0 — 2021-03-31
- 0.9.0 — 2020-07-30

## README

TypeScript Color Class
-----------

An opinionated TypeScript/JavaScript Color class.  This is what the JavaScript language should provide as the de facto `Color` object.

This module is a more simple alternative to the npm modules [color](https://www.npmjs.com/package/color) and [color-js](https://www.npmjs.com/package/color-js) with some important differences:

- written in TypeScript, exports an ES5 module, and ES4/legacy static build
- toString() always returns CSS-compatible color strings like `"#fff"` so the color objects can be used to change CSS style values or when creating strings, eg: `elm.style.color = new Color('azure')`
- in addition to RGB arrays, also accepts CSS strings as inputs, eg: `new Color('rgba(255,0,0,0.5)')` or `new Color('#ff00ff')`
- HSL calculations use floating point values between 0.0 and 1.0
- larger list of [color names](https://dsteinman.github.io/ts-color-class/colors.html)
- full test coverage using `npm run test` and for ES5 use `npm run test:es5`
- invalid constructor or methods throw errors
- all setter methods are immutable, chainable, and always return a new instance of `Color`
- the [static minified build](https://github.com/dsteinman/ts-color-class/tree/master/build) provides a global `Color` object available in any html file
- no dependencies
- small build size (22KB)

## Documentation

- [Color Class API](https://dsteinman.github.io/ts-color-class/api/Color.html)

## Install

#### Use NPM Module

```
import Color from 'ts-color-class';
```

#### Or use commonjs import syntax: 

```
var Color = require('ts-color-class');
```

#### Or use the static build

The static build file `color-class.min.js` is included in the [/build](https://github.com/dsteinman/ts-color-class/tree/master/build) directory.

```
<script type="text/javascript" src="color-class.min.js"></script>
```

## Usage

```
new Color( inputValue )
```

The `inputValue` can be one of:

- a CSS string, either a hex, rgb, rgba, or a [named color](https://dsteinman.github.io/ts-color-class/colors.html)
- an array of RGB values (and optionally an alpha channel)
- an HSL object

The constructor also accepts RGBA values in the form:

```
new Color( red, green, blue, alpha )
```

Here are some diifferent ways to define `red`:

```
new Color('red');
new Color('#f00');
new Color('#ff0000');
new Color('red', 0.5); // 50% transparent
new Color([255, 0, 0]);
new Color([255, 0, 0], 0.5); // 50% transparent
new Color(255, 0, 0);
new Color(255, 0, 0, 0.5); // 50% transparent
new Color('rgb(255, 0, 0)');
new Color('rgba(255, 0, 0, 0.5)'); // 50% transparent
new Color({ h: 0, s: 1, l: 0.5 });
new Color({ h: 0, s: 1, l: 0.5 }, 0.5); // 50% transparent
```

## Color Names

Any of the colors in the [named color list](https://dsteinman.github.io/ts-color-class/colors.html) can be used as the input value.

The hash of names and their RGB values can be accessed using:

```
Color.getNames()
```

## Methods

#### toString()

Returns a CSS-compatible 3 or 6 character hex string:

```
new Color('red').toString()
// returns "#f00"
```

If an alpha channel is supplied, and it is not equal to 1.0, an rgba string is returned:

```
new Color('red').alpha(0.5).toString()
// returns "rgba(255,0,0,0.5)"
```

If the alpha channel is equal to 0, then `transparent` is returned:

```
new Color('red').alpha(0).toString()
// returns "transparent"
```

In certain cases, such as when applying styles in CSS, using `console.log()`, or when manipulating strings, the `.toString()` is implied and can be omitted;

```
document.body.style.backgroundColor = new Color('red').darken(0.3);
```

```
console.log( "color = " + new Color('red').darken(0.3) );
```

```
var borderStyle = "1px solid " + new Color('red').darken(0.3);
myElement.style.border = borderStyle;
```

### Setter Methods

All setter methods are immutable and return a new instance of `Color`.  This means calling a method like `.alpha()` does not modify the object, but returns a new method with that alpha channel applied.  This is useful when making modifications to a base color value but not changing the original color.

```
var red = new Color('red');
var blue = new Color('blue');
var darkpurple = red.combine(blue.darken(0.2)).alpha(0.5);
console.log('red = '+red);
console.log('blue = '+ blue);
console.log('darkpurple = '+darkpurple);

// OUTPUT:
// red = #f00
// blue = #00f
// darkpurple = rgba(128,0,102,0.5)
```

#### alpha( value )

Sets the alpha channel (transparency):

```
new Color('red').alpha(0.5).toString();
// returns "rgba(255,0,0,0.5)"
```

#### lighten( amount )

Increases the lightness value (0 - 1):

```
new Color('#f00').lighten(0.1).toString();
// returns '#33f'
```

#### darken( amount )

Decreases the lightness value (0 - 1):

```
new Color('#f00').darken(0.5).toString();
// returns '#c00'
```

#### saturate( amount )

Increases the saturation value (0 - 1):

```
var cornsilk = new Color('corn silk 3');
console.log(cornsilk.getSaturation());
// returns 0.2187500000000001

// increase saturation fom 0.21 to 0.31:
console.log(cornsilk.saturate(0.1).getSaturation());
// returns 0.3187500000000001
```

#### desaturate( amount )

Decreases the saturation value (0 - 1):

```
new Color('#d3ccab'.desaturate(0.1).toString()
// returns '#cdc8b1'
```

#### shiftHue( amount )

Adjusts the hue value (0 - 1):

```
new Color(255, 255, 0).shiftHue(0.25).toString();
// returns '#00ff7f'
```

#### combine( Color, percent )

Combines the color with another.

Add a percentage parameter (0 - 1) to define how much of the new color to combine:
```
new Color('black').combine('red', 0.5).toString();
// returns '#800000'
```

#### tint( Color, percent )

Adjusts the hue toward another color based on a percentage value (0 - 1).

This is similar to `combine()` but only applies to the hue, not saturation or lightness.

```
new Color('red').tint('blue', 0.5).toString();
// returns '#0f0'
new Color('red').tint([0,0,1], 0.5).toString();
// also returns '#0f0'
```

#### hue( value )

Sets the hue value (0 - 1):

```
new Color('red').hue(0.23).toString()
// returns '#9eff00'
```

#### saturation( value )

Sets the saturation value (0 - 1):

```
new Color(100,50,50).saturation(0.5).toString()
// returns "#712626";
```

#### lightness( value )

Sets the lightness value (0 - 1);

```
new Color('#cdc8b1').lightness(0.5).toString()
// returns '#9b9164'
```

#### invert()

Inverts the color:

```
new Color('#fff').invert().toString()
// returns '#000'
```

#### red( value )

Sets the red value (0 - 255):

```
new Color('black').red(255).toString()
// returns '#f00'
```

#### green( value )

Sets the green value (0 - 255):

```
new Color('black').green(255).toString()
// returns '#0f0'
```

#### blue( value )

Sets the blue value (0 - 255):

```
new Color('black').green(255).toString()
// returns '#00f'
```

### Getter Methods

#### getRGB()

Returns the red, green, blue color values as an array:

```
console.log( new Color('red').getRGB() );
// returns [255,0,0]
```

#### getAlpha()

Returns the alpha channel value (0 - 1).

#### getHex()

Returns the hexidecimal css value (ignores alpha channel value).

#### getRed()

Returns the red value (0 - 255).

#### getGreen()

Returns the green value (0 - 255).

#### getBlue()

Returns the blue value (0 - 255).

#### getHSL()

Returns the hue, saturation, and lightness values as an object literal.

```
new Color('tan').getHSL()
// returns { h: 0.09523809523809527, s: 0.4374999999999999, l: 0.6862745098039216 }
```

#### getHue()

Returns the hue value (0 - 1);

#### getSaturation()

Returns the saturation value (0 - 1);

#### getLightness()

Returns the lightness value (0 - 1);

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