string-to-color

string-to-color is a library that deterministically generates an HSL color based on a given string.

It's useful for generating consistent colors for user avatars, boxes, and other visualizations where you need a color that is unique to a specific input value.

Installation

To install the library, use your favorite package manager:

npm install @marko19907/string-to-color

yarn add @marko19907/string-to-color

Usage

Generating a color

The library provides two functions, generateColor() and generateSecondaryColor(), that generate HSL colors from a given string.

import { generateColor, generateSecondaryColor } from "@marko19907/string-to-color";

const username = "JohnDoe";
const primaryColor = generateColor(username); // generates a primary color based on the username
const secondaryColor = generateSecondaryColor(username); // generates a secondary color based on the username

Both functions accept an optional ColorOptions object that can be used to customize the saturation, lightness, and alpha values of the generated color.

const options = { saturation: 50, lightness: 75, alpha: 100 };
const primaryColor = generateColor(username, options); // generates a primary color with custom saturation, lightness, and alpha values

If no options are provided, the default values of saturation: 75, lightness: 50, and alpha: 100 are used.

It is also possible to just provide a subset of the options, and the rest will be filled in with the default values.

const color = generateColor("abc", { saturation: 80 }); 

One can also call the function without any custom options like this. The rest will be filled in with the default values.

const color = generateColor("abc");

Generating a gradient

The library also provides a function, generateGradient(), that generates a gradient from a given string.

import { generateGradient } from "@marko19907/string-to-color";

const username = "JohnDoe";
const gradient = generateGradient(username); // generates a gradient based on the username

The gradient is generated using the generateColor() and generateSecondaryColor() functions, and is returned as a string in the format linear-gradient(45deg, primaryColor, secondaryColor).

The function accepts an optional angle parameter that sets the angle of the gradient, and two optional ColorOptions objects that can be used to customize each of the colors of the gradient.

const options = { saturation: 50, lightness: 75, alpha: 100 };
const secondaryOptions = { saturation: 100, lightness: 75, alpha: 100 };
const gradient = generateGradient(username, 90, options, secondaryOptions); // generates a gradient with custom options and a 90 degree angle

If no options are provided, the default values of angle: 45, saturation: 75, lightness: 50, and alpha: 100 are used for both colors of the gradient.

Usage with React and useMemo()

If you're using string-to-color in a React application, you can use the useMemo() hook to avoid unnecessary re-renders and improve performance.

Here's an example of generating a primary color based on a user's id using useMemo():

import { useMemo } from "react";
import { generateColor } from "@marko19907/string-to-color";

function Avatar({ user }) {
const primaryColor = useMemo(() => {
    return generateColor(user.id);
}, [user]);

return (
    <div style={{ backgroundColor: primaryColor }}>
        {user.name}
    </div>
);
}

License

This project is licensed under the MIT License. See the LICENSE file for details

Contributing

Pull requests and bug reports are welcome!