@patrtorg/consequatur-distinctio NPM

Overview

@patrtorg/consequatur-distinctio is a fast and lightweight javascript library for generating unique and beautiful colors from any texts or numbers.

Why @patrtorg/consequatur-distinctio?

There is no need to store colors in the database anymore, just use @patrtorg/consequatur-distinctio to generate colors at runtime and it will generate the same output every time, on any platform (Server, Browser or Mobile).
You can generate a unique color from UUID, MongoDB ObjectId or anything that can be converted to a string or number
You can generate a random color
You can control the color saturation and lightness
There is no need for an extra color library to change the color format or indicating whether the color brightness is light or dark
It's lightweight (~1.4KB gzipped)

Quick start

Using `npm` or `yarn`

$ npm install @patrtorg/consequatur-distinctio
# or
$ yarn add @patrtorg/consequatur-distinctio

ES6 Import:

import @patrtorg/consequatur-distinctio from '@patrtorg/consequatur-distinctio';

CommonJS (like nodejs, webpack, and browserify):

const @patrtorg/consequatur-distinctio = require('@patrtorg/consequatur-distinctio');

AMD (like RequireJS):

define(['@patrtorg/consequatur-distinctio'], function (@patrtorg/consequatur-distinctio) {
  // ...
})

Using `<script>`

Include @patrtorg/consequatur-distinctio.js or @patrtorg/consequatur-distinctio.min.js into your html file:

<script src="https://unpkg.com/@patrtorg/consequatur-distinctio/dist/@patrtorg/consequatur-distinctio.min.js" type="text/javascript"></script>
<script type="text/javascript">
  var color = @patrtorg/consequatur-distinctio('Hello world!');
</script>

Usage

/* Generate unique color from texts or numbers */

@patrtorg/consequatur-distinctio('Hello world!')
// { color: "#5cc653", isLight: true }

@patrtorg/consequatur-distinctio('bf545d4c-5360-4158-a572-bd3e204185a9', { format: 'rgb' })
// { color: "rgb(128, 191, 64)", isLight: true }

@patrtorg/consequatur-distinctio(123, {
  saturation: [35, 70],
  lightness: 25,
})
// { color: "#405926", isLight: false }

@patrtorg/consequatur-distinctio(123, {
  saturation: [35, 70],
  lightness: 25,
  differencePoint: 50,
})
// { color: "#405926", isLight: true }

// Generate random color
@patrtorg/consequatur-distinctio.random()
// { color: "#644cc8", isLight: false }

// Generate a random color with HSL format
@patrtorg/consequatur-distinctio.random({ format: 'hsl' })
// { color: "hsl(89, 55%, 60%)", isLight: true }

// Generate a random color in specific saturation and lightness
@patrtorg/consequatur-distinctio.random({
  saturation: 80,
  lightness: [70, 80],
})
// { color: "#c7b9da", isLight: true }

// Generate a random color but exclude red color range
@patrtorg/consequatur-distinctio.random({
  excludeHue: [[0, 20], [325, 359]],
})
// {color: '#53caab', isLight: true}

Examples

Avatar Placeholder

API

@patrtorg/consequatur-distinctio(value, options) ⇒ `Object`

Generate unique color from value

Params:

value (type: string|number)
options (type: Object, default: {})
options.format (type: string, default: 'hex'): The color format, it can be one of hex, rgb or hsl
options.saturation (type: number|Array, default: [50, 55]): Determines the color saturation, it can be a number or a range between 0 and 100
options.lightness (type: number|Array, default: [50, 60]): Determines the color lightness, it can be a number or a range between 0 and 100
options.differencePoint (type: number, defualt: 130): Determines the color brightness difference point. We use it to obtain the isLight value in the output, it can be a number between 0 and 255

Output:

color (type: string): The generated color
isLight (type: boolean): Determines whether the color is a light color or a dark color (It's good for choosing a foreground color, like font color)

@patrtorg/consequatur-distinctio.random(options) ⇒ `Object`

Generate random color

Params:

options (type: Object, default: {})
options.format (type: string, default: 'hex'): The color format, it can be one of hex, rgb or hsl
options.saturation (type: number|Array, default: [50, 55]): Determines the color saturation, it can be a number or a range between 0 and 100
options.lightness (type: number|Array, default: [50, 60]): Determines the color lightness, it can be a number or a range between 0 and 100
options.differencePoint (type: number, default: 130): Determines the color brightness difference point. We use it to obtain the isLight value in the output, it can be a number between 0 and 255
options.excludeHue (type: Array): Exclude certain hue ranges. For example to exclude red color range: [[0, 20], [325, 359]].