@marko19907/string-to-color

@marko19907/string-to-color turns any string (id, name, email, tag…) into a stable, good-looking color — every time.

Most “string to color” solutions effectively hash into RGB, which works, but often produces colors that are either muddy, too dark, or just visually uneven across a list of labels. This library is design-first: it generates colors in HSL and uses the “golden-ratio” hue distribution (inspired by Martin Ankerl’s post) to keep outputs evenly spaced and always pleasant to the human eye. It results in colors that feel intentionally chosen and less “random”, while still being fully deterministic.

Why use this over other “string to color” packages?

• Visually pleasing by default: it consistently produces balanced, visually pleasing colors from any string
• Deterministic: the same input always maps to the same color, perfect for avatars, tags, charts, labels, etc.
• Customizable: tweak saturation, lightness, and alpha to fit your design system or light/dark mode needs
• Built-in gradients: generate a matching secondary color and a ready-to-use CSS linear-gradient(...)
• HSL-first + RGB helpers: generate HSL directly or request RGB via conversion when needed
• Tree-shakeable: keeps your bundle size small by only including what you use

Demo

Check out the live demo of the library to see it in action!

The source code for the demo is available here

Installation

To install the library, use your favorite package manager:

npm install @marko19907/string-to-color

yarn add @marko19907/string-to-color

pnpm 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

There's an RGB version of the functions as well, generateColorRGB() and generateSecondaryColorRGB(), that generate RGB colors instead of HSL colors.

import { generateColorRGB, generateSecondaryColorRGB } from "@marko19907/string-to-color";

Use the HSL functions if you need to generate a color, and use the RGB functions if you really need to generate a color in RGB format. The RGB functions convert the generated HSL color to RGB, so they are slightly slower than the HSL functions and might lose some precision in the conversion.

Color Options

All 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 }); 

Shorthand options are also supported.

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

Note: The full property names take precedence over the shorthand options if both are provided.

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.

Using a Custom PRNG Algorithm

If you'd like to customize the PRNG algorithm used to generate the colors, you can easily do so.

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

const username = "JohnDoe";

// Pass the custom algorithm as an option
const primaryColor = generateColor(username, { algorithm: Alea });

This example imports the Alea algorithm from the library, then passes it as an option to the generateColor function. The library will use the custom algorithm to generate the color. You can replace the Alea algorithm with any other algorithm from the library or even pass your own custom PRNG algorithm.

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>
    );
}

Performance

Performance of the library depends on the chosen PRNG (Pseudo Random Number Generator) algorithm. A range of algorithms with different performance characteristics are provided, and the user can choose the one that best suits their needs. Below is a table comparing the relative speed of each algorithm.

| Algorithm | Speed | |-----------|-----------------| | Alea | ★★★★★ Very Fast | | Arc4 | ★★☆☆☆ Slow | | Tychei | ★★★★☆ Fast | | Xor128 | ★★★★★ Very Fast | | Xor4096 | ★★★★☆ Fast | | Xorshift7 | ★★★☆☆ Medium | | Xorwow | ★★★★☆ Fast |

These are rough estimates, and actual performance may vary. For more detailed performance data and comparisons of the PRNG algorithms, refer to the seedrandom repository.

When using the library in a React application, you can further improve performance by using the useMemo() hook to avoid unnecessary re-renders. See the "Usage with React and useMemo()" section in the README for an example. Other frameworks might offer a similar feature to React’s useMemo() hook.

Acknowledgments

The PRNG algorithms used in this library are sourced from the seedrandom library, and the ES module port is provided by the esm-seedrandom library.

This repository is based on a template by Matt Pocock. The template can be found in this repository mattpocock/pkg-demo and the video walkthrough on how to work with this repo is here.

License

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

Contributing

Pull requests and bug reports are welcome!