Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cdonohue/polychrome
🎨 Easy color manipulation in ~2kb (gzipped)
https://github.com/cdonohue/polychrome
color color-manipulation css-color css-in-js immutable palette tiny
Last synced: 12 days ago
JSON representation
🎨 Easy color manipulation in ~2kb (gzipped)
- Host: GitHub
- URL: https://github.com/cdonohue/polychrome
- Owner: cdonohue
- License: mit
- Created: 2017-03-21T14:06:26.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2018-02-11T02:12:26.000Z (over 6 years ago)
- Last Synced: 2024-10-11T23:46:29.232Z (28 days ago)
- Topics: color, color-manipulation, css-color, css-in-js, immutable, palette, tiny
- Language: TypeScript
- Homepage:
- Size: 378 KB
- Stars: 288
- Watchers: 11
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-tiny-js - polychrome - More of the same, <img align="top" height="24" src="./img/polychrome.svg"> (Colors / Reactive Programming)
- Colorful - Polychrome - A small library for parsing and manipulating colors. (Tools)
README
# `polychrome`
>A small `~2kB (gzipped)` library for parsing and manipulating colors
## Installation
>feel free to replace `yarn add` with `npm install`
```shell
$> yarn add polychrome
```
## Usage
```js
// using ES6 modules
import polychrome from "polychrome";
// using CommonJS modules
const polychrome = require("polychrome");
```
```js
// Make a polychrome color from hex, rgb(a), and hsl(a) strings
const red = polychrome("#F00");
// Get a string representation of a polychrome color in other formats
red.rgb() // "rgb(255,0,0)"
// Manipulate polychrome colors
const darkerRed = red.darken(20); // (pass in an integer percentage)
darkerRed.hsl() // "hsl(0,100%,40%)"
// Chain polychrome methods together before outputting
polychrome("#F00").darken(20).fadeOut(60).rgb() // "rgba(204,0,0,0.4)"
```
---
## API Reference
- [Polychrome](#polychrome-object)
- [Alpha](#alpha)
- [Hue](#hue)
- [Lightness](#lightness)
- [Mix](#mix)
- [Saturation](#saturation)
### Polychrome Object
`polychrome(colorString)`
>`colorString` can be a hex (3 or 6 digit), rgb(a), or hsl(a) string. Returns a `polychrome` object.
A polychrome object consists of the following properties:
- `rHex` - 2 character hex string representation of the red color channel
- `gHex` - 2 character hex string representation of the green color channel
- `bHex` - 2 character hex string representation of the blue color channel
- `r` - value of the red color channel [0 - 255]
- `g` - value of the green color channel [0 - 255]
- `b` - value of the blue color channel [0 - 255]
- `h` - hue of the color [0 - 360]
- `s` - saturation of the color [0 - 100]
- `l` - lightness of the color [0 - 100]
- `luma` - luma value of the color [0 - 255]
In addition to the above properties, the following methods are available to a `polychrome` for outputting CSS color strings:
- `.hex()` - returns a 6-digit hexadecimal CSS compatible color string
```js
polychrome("rgb(0, 0, 0)").hex() // "#000000"
```
- `.rgb()` - returns an rgb(a) CSS compatible color string
```js
// rgba will be used if an alpha value exists
polychrome("#000").rgb() // "rgb(0,0,0)"
polychrome("#000").fadeOut(60).rgb() // "rgba(0,0,0,.4)"
```
- `.hsl()` - returns an hsl(a) CSS compatible color string
```js
// hsla will be used if an alpha value exists
polychrome("#000").hsl() // "hsl(0,0%,0%)"
polychrome("#000").fadeOut(60).hsl() // "hsla(0,0%,0%,.4)"
```
### Alpha
- `.setAlpha(value)`
Returns a `polychrome` with an `alpha` value _absolutely_ set to `value`. No change occurs if value is omitted.
- `.fadeIn(percentage)`
Returns a `polychrome` faded in by `percentage`. Default `50` if no percentage is passed in.
- `.fadeOut(percentage)`
Returns a `polychrome` faded out by `percentage`. Default `50` if no percentage is passed in.
### Contrast
- `.contrast(dark, light)`
Checks `luma` value of `polychrome` and returns `dark` or `light` `polychrome` depending on the contrast level. If a contrast ratio of at least `4.5:1` is not met, the `dark`/`light` colors will be darkened / lightened until a valid ratio is met.
```js
polychrome("#000").contrast().rgb() // "rgb(255,255,255)"
polychrome("#DDD").contrast("#333", "#EEE").hex() // "#333333"
```
> `dark` and `light` can be a `String` _or_ `polychrome`. They default to `black (#000)` and `white (#FFF)` if params are not passed in.
### Hue
- `.setHue(value)`
Returns a `polychrome` with a `hue` value _absolutely_ set to `value`. No change occurs if value is omitted.
- `.spin(degrees)`
Returns a `polychrome` with a `hue` value _rotated_ `degrees`. Can be a positive or negative degree value. When bounds of `[0 - 360]` are reached, `hue` will continue in a circular fashion until it has been spun the full amount.
- `.complimentary()`
Returns a `polychrome` with a `hue` value _rotated_ `180 degrees`. Shorthand for `.spin(180)`.
### Lightness
- `.setLightness(value)`
Returns a `polychrome` with a `lightness` value _absolutely_ set to `value`. No change occurs if value is omitted.
- `.lighten(percentage)`
Returns a `polychrome` lightened by `percentage`. Default `10` if no percentage is passed in.
- `.darken(percentage)`
Returns a `polychrome` darkened by `percentage`. Default `10` if no percentage is passed in.
### Mix
- `.mix(otherColor)`
Returns a `polychrome` mixed with `otherColor`. `otherColor` can be another `polychrome` or a color string that will be parsed.
- `.tint()`
Returns a `polychrome` mixed with `white (#FFFFFF)`. Shorthand for `.mix("#FFFFFF")`.
- `.shade()`
Returns a `polychrome` mixed with `black (#000000)`. Shorthand for `.mix("#000000")`.
### Saturation
- `.setSaturation(value)`
Returns a `polychrome` with a `saturation` value _absolutely_ set to `value`. No change occurs if value is omitted.
- `.saturate(percentage)`
Returns a `polychrome` saturated by `percentage`. Default `10` if no percentage is passed in.
- `.desaturate(percentage)`
Returns a `polychrome` desaturated by `percentage`. Default `10` if no percentage is passed in.
- `.grayscale()`
Returns a `polychrome` with `saturation` set to `0`. Shorthand for `.setSaturation(0)`.
---
## License
> MIT License 2017 © Chad Donohue