{"id":15290742,"url":"https://github.com/marko19907/string-to-color","last_synced_at":"2025-09-10T00:40:58.346Z","repository":{"id":153164844,"uuid":"620307772","full_name":"Marko19907/string-to-color","owner":"Marko19907","description":"npm library that deterministically generates a color based on a given string.","archived":false,"fork":false,"pushed_at":"2023-09-17T10:18:22.000Z","size":159,"stargazers_count":6,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-08T19:21:46.266Z","etag":null,"topics":["color","color-generator","generator","gradient","javascript","library","npm-package","npmjs","string","tiny","typescript","webdevelopment"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@marko19907/string-to-color","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Marko19907.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-03-28T12:35:04.000Z","updated_at":"2025-03-21T11:20:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"92e174f4-0ed3-473f-a4f6-0b5eb03b190f","html_url":"https://github.com/Marko19907/string-to-color","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/Marko19907/string-to-color","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marko19907%2Fstring-to-color","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marko19907%2Fstring-to-color/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marko19907%2Fstring-to-color/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marko19907%2Fstring-to-color/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Marko19907","download_url":"https://codeload.github.com/Marko19907/string-to-color/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Marko19907%2Fstring-to-color/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274390653,"owners_count":25276408,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-09T02:00:10.223Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["color","color-generator","generator","gradient","javascript","library","npm-package","npmjs","string","tiny","typescript","webdevelopment"],"created_at":"2024-09-30T16:09:16.326Z","updated_at":"2025-09-10T00:40:58.324Z","avatar_url":"https://github.com/Marko19907.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# string-to-color\n\n[![npm version](https://img.shields.io/npm/v/@marko19907/string-to-color.svg)](https://www.npmjs.com/package/@marko19907/string-to-color)\n[![npm downloads per week](https://badgen.net/npm/dw/@marko19907/string-to-color)](https://www.npmjs.com/package/@marko19907/string-to-color)\n[![minified size](https://badgen.net/bundlephobia/min/@marko19907/string-to-color?label=minified)](https://bundlephobia.com/result?p=@marko19907/string-to-color)\n[![gzip size](https://badgen.net/bundlephobia/minzip/@marko19907/string-to-color?label=gzipped)](https://bundlephobia.com/result?p=@marko19907/string-to-color)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n[![Build](https://github.com/Marko19907/string-to-color/actions/workflows/main.yml/badge.svg?branch=main\u0026label=Build)](https://github.com/Marko19907/string-to-color/actions/workflows/main.yml)\n[![Dev build](https://github.com/Marko19907/string-to-color/actions/workflows/main.yml/badge.svg?branch=dev\u0026label=Dev%20build)](https://github.com/Marko19907/string-to-color/actions/workflows/main.yml)\n\n\nstring-to-color is a library that deterministically generates an HSL color based on a given string.\n\nIt's useful for generating consistent colors for user avatars, boxes, and other visualizations where you need\na color that is unique to a specific input value. \n\nThe generated colors are also customizable, allowing you to tweak the saturation, lightness, and alpha values of the generated color to suit your needs and match your design.\n\nTree shaking is supported too, allowing for more efficient bundling of your code.\n\n## [Demo](https://marko19907.github.io/string-to-color-demo/)\nCheck out the live demo of the library to see it in action!\n\nThe source code for the demo is available [here](https://github.com/Marko19907/string-to-color-demo)\n\n## Installation\n\nTo install the library, use your favorite package manager:\n\n```bash\nnpm install @marko19907/string-to-color\n```\n\n```bash\nyarn add @marko19907/string-to-color\n```\n\n```bash\npnpm add @marko19907/string-to-color\n```\n\n## Usage\n\n### Generating a color\n\nThe library provides two functions, `generateColor()` and `generateSecondaryColor()`, that generate HSL colors from a given string.\n\n```js\nimport { generateColor, generateSecondaryColor } from \"@marko19907/string-to-color\";\n\nconst username = \"JohnDoe\";\nconst primaryColor = generateColor(username); // generates a primary color based on the username\nconst secondaryColor = generateSecondaryColor(username); // generates a secondary color based on the username\n```\n\nThere's an RGB version of the functions as well, `generateColorRGB()` and `generateSecondaryColorRGB()`, that generate RGB colors instead of HSL colors.\n\n```js\nimport { generateColorRGB, generateSecondaryColorRGB } from \"@marko19907/string-to-color\";\n```\n\nUse 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.\nThe 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.\n\n#### Color Options\n\nAll functions accept an optional `ColorOptions` object that can be used to customize the\nsaturation, lightness, and alpha values of the generated color.\n\n```js\nconst options = { saturation: 50, lightness: 75, alpha: 100 };\nconst primaryColor = generateColor(username, options); // generates a primary color with custom saturation, lightness, and alpha values\n```\n\nIf no options are provided, the default values of `saturation: 75`, `lightness: 50`, and `alpha: 100` are used.\n\nIt is also possible to just provide a subset of the options, and the rest will be filled in with the default values.\n\n```js\nconst color = generateColor(\"abc\", { saturation: 80 }); \n```\n\nShorthand options are also supported.\n\n```js\nconst color = generateColor(\"abc\", { s: 80 }); \n```\n\n**Note:** The full property names take precedence over the shorthand options if both are provided.\n\nOne can also call the function without any custom options like this. The rest will be filled in with the default values.\n\n```js\nconst color = generateColor(\"abc\");\n```\n\n### Generating a gradient\n\nThe library also provides a function, `generateGradient()`, that generates a gradient from a given string.\n\n```js\nimport { generateGradient } from \"@marko19907/string-to-color\";\n\nconst username = \"JohnDoe\";\nconst gradient = generateGradient(username); // generates a gradient based on the username\n```\n\nThe gradient is generated using the `generateColor()` and `generateSecondaryColor()` functions, and is returned as a string in the format `linear-gradient(45deg, primaryColor, secondaryColor)`.\n\nThe 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.\n\n```js\nconst options = { saturation: 50, lightness: 75, alpha: 100 };\nconst secondaryOptions = { saturation: 100, lightness: 75, alpha: 100 };\nconst gradient = generateGradient(username, 90, options, secondaryOptions); // generates a gradient with custom options and a 90 degree angle\n```\n\nIf 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.\n\n### Using a Custom PRNG Algorithm\n\nIf you'd like to customize the PRNG algorithm used to generate the colors, you can easily do so.\n\n```js\nimport { Alea, generateColor } from \"@marko19907/string-to-color\";\n\nconst username = \"JohnDoe\";\n\n// Pass the custom algorithm as an option\nconst primaryColor = generateColor(username, { algorithm: Alea });\n```\n\nThis example imports the `Alea` algorithm from the library, then passes it as an option to the `generateColor` function. \nThe library will use the custom algorithm to generate the color. \nYou can replace the `Alea` algorithm with any other algorithm from the library or even pass your own custom PRNG algorithm.\n\n\n### Usage with React and `useMemo()`\n\nIf you're using string-to-color in a React application, you can use the `useMemo()` hook to avoid unnecessary re-renders and improve performance.\n\nHere's an example of generating a primary color based on a user's id using useMemo():\n\n```js\nimport { useMemo } from \"react\";\nimport { generateColor } from \"@marko19907/string-to-color\";\n\nfunction Avatar({ user }) {\nconst primaryColor = useMemo(() =\u003e {\n    return generateColor(user.id);\n}, [user]);\n\nreturn (\n    \u003cdiv style={{ backgroundColor: primaryColor }}\u003e\n        {user.name}\n    \u003c/div\u003e\n);\n}\n```\n\n## Performance\n\nPerformance of the library depends on the chosen PRNG (Pseudo Random Number Generator) algorithm. \nA range of algorithms with different performance characteristics are provided, and the user can choose the one that best suits their needs.\nBelow is a table comparing the relative speed of each algorithm. \n\n| Algorithm | Speed           |\n|-----------|-----------------|\n| Alea      | ★★★★★ Very Fast |\n| Arc4      | ★★☆☆☆ Slow      |\n| Tychei    | ★★★★☆ Fast      |\n| Xor128    | ★★★★★ Very Fast |\n| Xor4096   | ★★★★☆ Fast      |\n| Xorshift7 | ★★★☆☆ Medium    |\n| Xorwow    | ★★★★☆ Fast      |\n\nThese are rough estimates, and actual performance may vary. \nFor more detailed performance data and comparisons of the PRNG algorithms, refer to the [seedrandom repository](https://github.com/davidbau/seedrandom#other-fast-prng-algorithms).\n\nWhen using the library in a React application, you can further improve performance by using the `useMemo()` hook to avoid unnecessary re-renders.\nSee the [\"Usage with React and useMemo()\"](#usage-with-react-and-usememo) section in the README for an example.\nOther frameworks might offer a similar feature to React’s `useMemo()` hook.\n\n## Acknowledgments\n\nThe PRNG algorithms used in this library are sourced from the [seedrandom library](https://github.com/davidbau/seedrandom#other-fast-prng-algorithms),\nand the ES module port is provided by the [esm-seedrandom library](https://github.com/shanewholloway/js-esm-seedrandom).\n\nThis repository is based on a template by Matt Pocock.\nThe template can be found in this repository [mattpocock/pkg-demo](https://github.com/mattpocock/pkg-demo)\n\n## License\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details\n\n## Contributing\nPull requests and bug reports are welcome! \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarko19907%2Fstring-to-color","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarko19907%2Fstring-to-color","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarko19907%2Fstring-to-color/lists"}