JavaScript Library for creating random pleasing colors and color schemes

Last update: Dec 22, 2022

Related tags

Overview

#PleaseJS

www.checkman.io/please

Please.js is a polite companion that wants to help you make your projects beautiful. It uses HSV color space to create random pleasing colors as well as color schemes based on a given color. It has two core functions and a bunch of little helpers for you to use.

Please.make_color();
//or
Please.make_scheme(
{
	h: 145,
	s: .7,
	v: .6
},
{
	scheme_type: 'triadic',
	format: 'rgb-string'
});

##Core

make_color

Please.make_color({options})

The make_color function by default will generate and return a random hex string using the golden ratio to ensure that the color will look nice on your screen.

You can also pass an options object to make_color and have it do a whole bunch of different things.

make_color options:

hue: (0-360) By setting the hue, you determine the color.
saturation: (0.0-1.0) By setting the saturation, you determine the distance from gray.
value: (0.0-1.0) By setting the value, you determine the balance between black and white.
base_color: ('the name of an HTML color') Setting a base_color (e.g. 'pink') will create a random color within the HSV range of the chosen color. Please will recognize any of the 146 standard HTML colors, it has a very good memory.
greyscale | grayscale: (true/false) Setting either greyscale or grayscale (but we all know which one is correct) to true will cause all of the colors you generate to be within the grey or gray range. This is effectively the same as setting your saturation to 0.
golden: (true/false) Setting golden to true randomizes your hue (overrides hue setting) and makes you a spectacular color based on the golden ratio. It's so good, it's the default. Make sure to turn it off if you want to have more control over your generated colors.
full_random: (true/false) Setting full_random to true will make Please lose its mind. It will completely randomize the hue, saturation, and value of the colors it makes.
colors_returned: (1-infinity) Setting colors_returned to higher than 1 will return an array full of the colors Please has made for you. If you set it to 1, you'll just get the one color! It makes a sort of sense if you think about it.
format: ('format string') Setting format string, will change the format of what make_color will return for you. The options are as follows (example is the color black):
- 'hex' = '#000000'
- 'rgb' = {r: 0, g: 0,b: 0}
- 'rgb-string' = 'rgb(0,0,0)'
- 'hsv' = {h: 0, s: 0, v: 0}

Here are the defaults for each option:

{
	hue: null,
	saturation: null,
	value: null,
	base_color: '',
	greyscale: false,
	grayscale: false,
	golden: true,
	full_random: false,
	colors_returned: 1,
	format: 'hex',
}

Here is an example of a fully random color call:

Please.make_color({
	golden: false,
	full_random: true
});

Here is an example that will produce 100 reds as RGB strings:

Please.make_color({
	golden: false,
	base_color: 'red',
	colors_returned: 100,
	format: 'rgb-string'
});

make_scheme

The second core function allows Please to make a color scheme for you.

Please.make_scheme(base_color,{options})

The make scheme function will return a series of colors based upon the color and options you feed it. The base_color must be in HSV color space and is an object in the format of

{
	h: ___,
	s: ___,
	v: ___
}

make_scheme options:

scheme_type
- 'monochromatic' | 'mono' - Makes a 5 color scheme using your provided color, all the colors will be fairly similar to each other.
- 'complementary' | 'complement' - Makes a two color scheme using your provided color, the 2nd color will be the complement of the 1st, such that mixing them will create a neutral grey.
- 'split-complementary' | 'split-complement' | 'split' - Makes a three color scheme where the 2nd and 3rd colors are at a 30 degree split from the complement of the 1st color.
- 'double-complementary' | 'double-complement' | 'double' - Makes a four color scheme where the 2nd color is the complement of the 1st, and the 3rd and 4th colors are complements of each other at a 30 degree ofset from the first pair
- 'analogous' | 'ana' - Makes a six color scheme where each additional color is offset from the 1st by 20 degrees.
- 'triadic' | 'triad' | 'tri' - Makes a 3 color scheme where the 2nd and 3rd color are equally spaced from the 1st.
format: ('format string') Setting format string, will change the format of what make scheme will return for you. The options are as follows (example is the color white):
- 'hex' = '#ffffff'
- 'rgb' = {r: 255, g: 255,b: 255}
- 'rgb-string' = 'rgb(255,255,255)'
- 'hsv' = {h: 0, s: 0, v: 1}

Here is an example of a complementary scheme in hex:

Please.make_scheme(
{
	h: 130,
	s: .7.
	v: .75
},
{
	scheme_type: 'complement',
	format: 'hex'
});

Here is an example that will produce a triadic scheme in rgb-strings:

Please.make_scheme(
{
	h: 130,
	s: .7.
	v: .75
},
{
	scheme_type: 'triadic',
	format: 'rgb-string'
});

Here are the defaults for each option:

{
	scheme_type: 'analogous',
	format: 'hex'
}

Other Methods

Please also has some bonus features. It allows you to convert freely between the color formats of RGB, HSV, and HEX.

RGB_to_HEX() HEX_to_RGB() RGB_to_HSV() HSV_to_RGB() HEX_to_HSV() HSV_to_HEX()

conversion from HSV or RGB expect an object with the properties

{
	r: 0-255,
	g: 0-255,
	b: 0-255
}

and

{
	h: 0-360,
	s: 0.0-1.0,
	v: 0,0-1.0
}

respectively, while converstions from HEX expect a string. Return formats are modeled the same way as the arguments.

In addition Please, can convert from an HTML color name into HEX, RGB, or HSV.

NAME_to_HEX()
NAME_to_RGB()
NAME_to_HSV()

These functions take a string and return a HEX string or an RGB/HSV object.

I hope you enjoy using Please. Have fun, and remember to say the magic word.

License

MIT

Comments

Any way to fork and create website?

@Fooidge - I love this library; I use it all the time to generate soothing color palettes.

More specifically, I used the demo feature on website a lot just to generate color palettes to use for other projects. As @billcastillo mentioned in #72, it looks as though the domain has expired and the website is no longer available.

Is it possible for me to fork this repo and stand up the website again? Or do you have other files you used to generate the website? If you can point me in the right direction or get me started, I'd be more than happy to stand up the website again and maintain this.

Please let me know - I really miss the site!

opened by gtallen1187 8
Need for better/any documentation

Seems like a great library but it would help if there were even minimal documentation for various options possible and the differences.

The code is clean and easy to read but still needs some knowledge of color theory to get started. It'll also enable others to make enhancements and send pull requests for minor changes.

Please consider starting a wiki with minimal info and I'm sure others chime in to improve it over time.

opened by karanjassar 7
Mixed return values with colors_returned option

colors_returned: (1-infinity) Setting colors_returned to higher than 1 will return an array full of the colors Please has made for you. If you set it to 1, you'll just get the one color! It makes a sort of sense if you think about it.

In my opinion it would make a lot of more sense if the function would always return an array of strings when the color_returned is used.

In many use cases the number comes from a dynamic value and now the result needs to be converted for consistent results.

opened by rikukissa 6
Adding support for seed based colour generation
As discussed earlier I've introduced support for generating colours based on a seed.

A seed is a string of characters you can pass to the make_colour() function; the same string of characters will always return the same colour.

Example:

// Will always return "#bf8172" Please.make_color({seed: 'foobar'}); // Will always return ["#72bf9c", "#9572bf", "#bf9972"] Please.make_color({seed: 'GitHub', colors_returned: 3});

Note that if the colour generation code changes in a future version of the library, the colours generated for specific seeds might change (depends on the number of times the random functions are called).
opened by MaciekBaron 6
Added new from_hash feature and fixed the documentation.
I did multiple changes on the project.

Fixed the documentation in the README.md and added tons of markdown.

Created demo directory with the page from: http://www.checkman.io/please/

Added a new feature that maps any string to the same color every time. (useful for use with ChartJS)
opened by ibarrajo 5
Use a hex color as "base_color"
Hi !

It would be great to add the ability to use a color in hex as "base_color".

Example :

Please.make_color({ base_color: '#FF0000' });
opened by MaximeWillinger 5
Generate constant color for an object based on a key.
Hello! Thanks a lot for the amazing library!

In my project I need to create constant colors for users and chats based on their id: Uuid. I looked for a solution and found the PleaseJS library that is able to generate nice random colors. I have thought that I can override your random function to produce constant colors for any given id. But it was even easier! I just need to submit my id as seed and everything works! Cool! I use it this way:

Please.make_color({seed: id});

But I still need to monkey-patch your library because there is no way to use my own seed value now. Maybe we should add it? This will enable such crazy use-cases as mine is. :heart_eyes:
opened by s-panferov 4
Black, Grays return red shades

I'm not sure if this is just me, but I tested Please.make_color with base_color gray and black, and it always returns red shades. I'm fairly new at coding so please let me know if it's me being a n00b :)

var colors = Please.make_color({ base_color: 'gray', colors_returned: 20, format:'hex' });

opened by donnieberg 4
make_color has inconsistent return type

https://github.com/Fooidge/PleaseJS/blob/master/Please.js#L551

I'm curious why this returns the color as a string if there's only one result, but an array otherwise. Makes embedding code sort of convoluted. I didn't submit a patch because I assume there's a reason, but I just wanted to know what it is.

opened by ixtli 4
How to output results of Please.js functions

Being a web designer, with limited JS skills, I would like to know how should I output results of Please.js functions?

For example, the elementary Please.make_color(); function, how should I get the output of it?

Sorry for this type of question :)

Mirko

opened by fluxxus 4
Help with outputing color values to colored divs, similar to example page

Hi, I want to create something similar to the example page of Please.js. Basically to have a few divs, and have their background color changed based upon function called.

It is easy for just one color, but how to output the value of a function that creates a color scheme?

Here is the fiddle with one color, and the setup is ready with four divs to accept the values for a color scheme, but I don't know how to do it.

http://jsfiddle.net/pefqj1uu/1/

opened by fluxxus 3

Invalid conversion rgb-hsv

Hi! Thank you for this module.

var color = '#1ba1e2';
var color_rgb = Please.HEX_to_RGB(color);

console.log("Hex: ", color);
console.log("Rgb: ", color_rgb);
console.log("Rgb: ", Please.HSV_to_RGB(Please.RGB_to_HSV(color_rgb)));

I hav next result:

Hex: #1ba1e2 Rgb: {r: 27, g: 161, b: 226} Rgb: {r: 26, g: 161, b: 226}

opened by olton 0

Fix broken headings in Markdown files

GitHub changed the way Markdown headings are parsed, so this change fixes it.

See bryant1410/readmesfix for more information.

Tackles bryant1410/readmesfix#1

opened by bryant1410 0
human distinguishable

Is there an option to ensure the generated colors from colors_returned are human distinguishable?

The Make a few. demo that generates 4 colors are often hard to tell apart.

opened by bdkent 0
Generate Material Design shades from single color

Cool library!

I am working on a project where the client picks a color (or a color and a compliment) and it reskins a whole CMS driven Material Design site.

Is there any interest in adding a

Please.make_scheme({ scheme_type: 'material', //set scheme type format: 'hex' //give it to us in rgb });

This may be too specific and I'm not sure if anyone else would want it.

opened by ShaggyDude 0

Releases(0.4.2)

0.4.2(Nov 10, 2014)

Bug fix for HSV_to_RGB
Source code(tar.gz)
Source code(zip)

0.4.0(Oct 24, 2014)

//New Feature!
Please.make_color({
    seed: 'Fooidge'
});

Thanks to MaciekBaron

//Now works as expected
Please.make_color({
    base_color: 'black'
});

Thanks to Donnieberg

Source code(tar.gz)
Source code(zip)

0.3.0(Sep 16, 2014)

PleaseJS 0.3.0 - Gray Aluminium

You now have the ability to pass a hex string into base_color.

//still works
Please.make_color({
    base_color: 'skyblue';
});

//works now!
Please.make_color({
    base_color: '#0fbabc';
});

//also works
Please.make_color({
    base_color: '0fbabc';
});

//even this works
Please.make_color({
    base_color: 'abc';
});

As always, have fun!

Source code(tar.gz)
Source code(zip)

0.2.6(Sep 16, 2014)

Tested poorly. Bug fixed caused a regression. Remind me to Jasmine this thing.

Fixed. Tested this time.
Source code(tar.gz)
Source code(zip)
0.2.5(Sep 16, 2014)

When using Please.make_color({base_color: "SOME_COLOR"}) there was a rare bug that could occur which returned a NaN. It has been squashed.
Source code(tar.gz)
Source code(zip)
0.2.3(Sep 15, 2014)

Source code(tar.gz)
Source code(zip)
0.2.1(Aug 30, 2014)

Source code(tar.gz)
Source code(zip)