ethereal-color

v0.0.5

Published

2 years ago

Fast, simple, easy library to work with colors: single, palette's, gradient and more

Downloads

0High
0Medium
0Low

lakscastro

color generator gradient palette converter rgb library lib typescript nodejs js ts javascript

Try demo

Visite library web page clicking here
Or, visit a demo project clicking here

Installation

1. Package

Npm

npm i ethereal-color

Yarn

yarn add ethereal-color

2. CDN

<script type="text/javascript" src="https://unpkg.com/[email protected]/lib/index.js"></script>

Quickstart

1. Package

~/index.html

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Ethereal Color Quickstart with Package</title>
</head>

<body>
</body>

<script src="./app.js"></script>

</html>

~/app.js

// ES6
import EtherealColor from "ethereal-color";

// CommomJS
const EtherealColor = require("ethereal-color");

const { Color, Palette, Gradient, Converter } = EtherealColor;

// ...Now it's up to you, enjoy this API

2. CDN

~/index.html

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Ethereal Color Quickstart with CDN</title>
    <script type="text/javascript" src="https://unpkg.com/[email protected]/lib/index.js"></script>
</head>

<body>
</body>

<script>
    const { Color, Converter, Gradient, Palette } = EtherealColor;
  
    // ...Now it's up to you, enjoy this API
</script>

</html>

Color Types

For all examples below, RGB will be used, but you can also use the Hexadecimal or HSL color format
| Color Format | Color Key | Color Object Type | Color String | |--------------|-----------|----------------------------------------------|------------------| | RGB | rgb | Rgb: { r: number, g: number, b: number } | rgb(R, G, B) | | Hexadecimal | hex | Hex: { r: string, g: string, b: string } | #rrggbb | | HSL | hsl | Hsl: { h: number, s: number, l: number } | hsl(H, S%, L%) |

Color Function

Default return

If you call the Color function without sending any arguments, white will be returned

const color = Color();

color.get("rgb").string; // rgb(255, 255, 255)

1. Color API Type (ColorAPI)

{
  get: (format: 'rgb' | 'hex' | 'hsl') => { string: string, object: Rgb | Hex | Hsl  };
  set: (newColor: Rgb | Hex | Hsl | ColorString) => void;
  random: (palette?: PaletteAPI) => void;
}

2. Create a Color API

A Color API is used to represent a separate color, a single color within that infinity of colors that exist

// Way 1 - Using default color: rgb(255, 255, 255)
const color = Color();

color.get("rgb").string; // rgb(255, 255, 255)
color.get("rgb").object; // { r: 255, g: 255, b: 255 }


// Way 2 - Using custom color: Red, for example
const color = Color("rgb(255, 0, 0)");

color.get("rgb").string; // rgb(255, 0, 0)
color.get("rgb").object; // { r: 255, g: 0, b: 0 }


// Way 3 - Using custom color object: Blue, for example
const color = Color({ r: 0, g: 0, b: 255 });

color.get("rgb").string; // rgb(0, 0, 255)
color.get("rgb").object; // { r: 0, g: 0, b: 255 }

3. Change the color of an object at run time

const color = Color();

color.get("rgb").string; // rgb(255, 255, 255)

color.set("rgb(150, 150, 150)");

color.get("rgb").string; // rgb(150, 150, 150)

4. Generate a random color

// Way 1 - A totally random color
const color = Color();
color.random();

color.get("rgb").string; // rgb(??, ??, ??)


// Way 2 - Within the range of a palette
const palette = Palette([Color("rgb(120, 100, 160)"), Color("rgb(130, 180, 200)")]);
// Start: rgb(120, 100, 160)
// End: rgb(130, 180, 200)

const color = Color();
color.random(palette);

color.get("rgb").string; // rgb(X, Y, Z)
// 120 <= X <= 130
// 100 <= Y <= 180
// 160 <= Z <= 200

Palette Function

Default return

If you try to create a palette without sending anything as a parameter, a palette will be created using white as the base

// this...
const palette = Palette();

// ...is the same thing as this:
const palette = Palette(Color());
// ...then:
// Start: rgb(215, 215, 215)
// End: rgb(255, 255, 255)

1. Palette API Type (PaletteAPI)

{
  get: () => [ColorAPI, ColorAPI];
  set: (color: ColorAPI | [ColorAPI, ColorAPI], options?: { range: number }) => void;
  random: (options?: { range: number }) => void;
}

2. Create a Palette API

A Palette API is used to reference a range of colors, that is, where a certain range begins, and where it ends

// Way 1 - Using defaut range: 40
const color = Color("rgb(150, 150, 150)");

const palette = Palette(color);
// Start: rgb(110, 110, 110)
// End: rgb(190, 190, 190)


// Way 2 - Using custom range: 100
const color = Color("rgb(150, 150, 150)");

const palette = Palette(color, { range: 100 /* need to specify */ });
// Start: rgb(50, 50, 50)
// End: rgb(250, 250, 250)


// Way 3 - Create a custom palette
const startColor = Color("rgb(65, 65, 0)");
const endColor = Color("rgb(230, 230, 230)");

const palette = Palette([startColor, endColor]);
// Start: rgb(65, 65, 0)
// End: rgb(230, 230, 230)

3. Change the value of the palette at run time

const color = Color("rgb(120, 150, 150)");

const palette = Palette(color);
// Start: rgb(80, 110, 110)
// End: rgb(160, 190, 190)

const otherColor = Color("rgb(20, 40, 10)");

palette.set(otherColor, { range: 10 });
// Start: rgb(10, 30, 0)
// End: rgb(30, 50, 20)

4. Generate a random palette

const palette = Palette(); // default color: white - rgb(255, 255, 255)
// Start: rgb(215, 215, 215)
// End: rgb(255, 255, 255)

// Now...
// Optionally you can send the options for the random palette
palette.random({ range: 90 });
// Start: rgb(??, ??, ??)
// End: rgb(??, ??, ??)

Gradient Function

Default return

If you don't send anything to the Gradient function, it will return a gradient from a white palette

// ...this
const gradient = Gradient();
// [rgb(215, 215, 215)]

// ...is the same thing as this:
const gradient = Gradient(Palette());
// ...then:
// [rgb(215, 215, 215), ..., rgb(255, 255, 255)]

1. Gradient API Type (GradientAPI)

{
  toStringArray: (format: 'rgb' | 'hex' | 'hsl') => string[];
  toObjectArray: (format: 'rgb' | 'hex' | 'hsl') => Rgb[] | Hex[] | Hsl[];
  toColorArray: () => ColorAPI[];
  set: (palette: PaletteAPI) => void;
  random: (options?: { count: number }) => void;
}

2. Create a Gradient API

A Gradient object is used to represent a sequence of colors, which sequence consists of a starting color and an ending color

// 1. Init start and end colors:
const startColor = Color("rgb(255, 0, 0)");
const endColor = Color("rgb(0, 0, 255)");

// 2. Init palette:
const palette = Palette([startColor, endColor]);

// 3. Now, the gradients:

// Way 1 - Create a default gradient:
const gradient = Gradient(palette); // Precision by default: 5

// Note: All arrays will have the specified size, in this case, by default it will be 5
gradient.toStringArray("rgb"); // ["rgb(255, 0, 0)", ..., rgb(0, 0, 255)]
gradient.toObjectArray("rgb"); // [{ r: 255, 0, 0 }, ..., { r: 0, g: 0, b: 255 }]
gradient.toColorArray("rgb"); // [ColorAPI, ..., ColorAPI]


// Way 2 - Create with custom precision
const gradient = Gradient(palette, { count: 20 }); // Custom precision: 20

// Note: All arrays will have the specified size, in this case, this size will be 20
gradient.toStringArray("rgb"); // ["rgb(255, 0, 0)", ..., rgb(0, 0, 255)]
gradient.toObjectArray("rgb"); // [{ r: 255, 0, 0 }, ..., { r: 0, g: 0, b: 255 }]
gradient.toColorArray("rgb"); // [ColorAPI, ..., ColorAPI]

3. Change the value of the Gradient at run time

// Init a gradient API with default precision 5...
const gradient = Gradient();

// ...then
gradient.toStringArray("rgb"); // ["rgb(215, 215, 215)", ..., "rgb(255, 255, 255)"]

// Now, create a simple palette...
const palette = Palette([Color("rgb(100, 100, 100"), Color("rgb(200, 200, 200)"))]);

// ...and use set() to change gradient value (optionally, you can set other options too)
gradient.set(palette, { count: 50 });
gradient.toStringArray(); // ["rgb(100, 100, 100)", ..., "rgb(200, 200, 200)"]

4. Generate a random gradient

const gradient = Gradient();

// Optionally you can send the options for the random gradient
gradient.random({ count: 50 });

gradient.toStringArray(); // ["rgb(??, ??, ??)", ..., "rgb(??, ??, ??)"]

Converter Function

Note: keep this table in mind when using this function:

Create a Converter API

The Convert object is a separate object, that is, it works as if it were a static class and can help you convert different color formats without having to create another object. The library uses this object under the hood to work with the different color formats.

// New converter object
const converter = Converter();

How to use

1. `hexToRgb()`

Description: Function that receives an object in the "hex" format and returns an object in the "rgb" format
Type: (color: Hex) => Rgb

const output = converter.hexToRgb({ r: "ff", g: "ff", b: "ff" });
// output = { r: 255, g: 255, b: 255 }

2. `hslToRgb()`

Description: Function that receives an object in the "hsl" format and returns an object in the "rgb" format
Type: (color: Hsl) => Rgb

const output = converter.hslToRgb({ h: 0, s: 0, l: 100 });
// output = { r: 255, g: 255, b: 255 }

3. `rgbToHex()`

Description: Function that receives an object in the "rgb" format and returns an object in the "hex" format
Type: (color: Rgb) => Hex

const output = converter.rgbToHex({ r: 255, g: 255, b: 255 });
// output = { r: "ff", g: "ff", b: "ff" }

4. `rgbToHsl()`

Description: Function that receives an object in the "hex" format and returns an object in the "rgb" format
Type: (color: Rgb) => Hsl

const output = converter.rgbToHsl({ r: 255, g: 255, b: 255 });
// output = { h: 0, s: 0, l: 100 }

Some frequently asked questions

1. Can I work using different color formats?

Yes, it is totally possible, although there may be some minor incompatibilities, for example: every hex color can be represented in the RGB, but not every RGB color can be represented in the hex format

const color = Color("rgb(150, 140, 160)");

color.get("hex").string; // #968ca0
color.get("hsl").string; // hsl(270, 10%, 59%)

color.set("#ffffff");

color.get("rgb"); // rgb(255, 255, 255)
color.get("hsl"); // hsl(0, 0%, 100%)

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Try demo

Installation

1. Package

2. CDN

Quickstart

1. Package

2. CDN

Color Types

Color Function

Default return

1. Color API Type (ColorAPI)

2. Create a Color API

3. Change the color of an object at run time

4. Generate a random color

Palette Function

Default return

1. Palette API Type (PaletteAPI)

2. Create a Palette API

3. Change the value of the palette at run time

4. Generate a random palette

Gradient Function

Default return

1. Gradient API Type (GradientAPI)

2. Create a Gradient API

3. Change the value of the Gradient at run time

4. Generate a random gradient

Converter Function

Create a Converter API

How to use

1. hexToRgb()

2. hslToRgb()

3. rgbToHex()

4. rgbToHsl()

Some frequently asked questions

1. Can I work using different color formats?

1. `hexToRgb()`

2. `hslToRgb()`

3. `rgbToHex()`

4. `rgbToHsl()`