{"_id":"@a.r.i_eze/color-matcher","_rev":"6-085e9913b4052e7d5aa9a79f65a65152","name":"@a.r.i_eze/color-matcher","dist-tags":{"latest":"1.0.7"},"versions":{"1.0.0":{"name":"@a.r.i_eze/color-matcher","version":"1.0.0","keywords":["color","lab","deltaE","nearest-color","color-matcher","hex","rgb","converter"],"author":{"name":"A.R.I Eze"},"license":"MIT","_id":"@a.r.i_eze/color-matcher@1.0.0","maintainers":[{"name":"a.r.i_eze","email":"kingsley2169@icloud.com"}],"homepage":"https://github.com/kingsley2169/color-matcher#readme","bugs":{"url":"https://github.com/kingsley2169/color-matcher/issues"},"dist":{"shasum":"2d4dad916a825613ebb9ca77c0916d1a374f59b2","tarball":"https://registry.npmjs.org/@a.r.i_eze/color-matcher/-/color-matcher-1.0.0.tgz","fileCount":2,"integrity":"sha512-4x0D2ZxS3pMuNcCfKL3eQRvnsAKTT7NyqwawVUGmvS8FwOENCOwnP9fphavttwnaYxbePL1yJ+y5Pbki62wjNg==","signatures":[{"sig":"MEUCIQDZ0BCm/KsmFYdY0M95ohK3z8IPJzQpl4sJv3U/rkb7vwIgNiUr75wogntCMlg7E1DrIMuZD4xOKC96Q77/7TMwnOc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":6578},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"}},"gitHead":"aa55810b6f51e9a4044882488965cc21b75fc54e","scripts":{"test":"vitest","build":"tsup"},"_npmUser":{"name":"a.r.i_eze","email":"kingsley2169@icloud.com"},"repository":{"url":"git+https://github.com/kingsley2169/color-matcher.git","type":"git"},"_npmVersion":"11.5.2","description":"A module to find the closest human-readable name for any color using Lab color space and Delta-E algorithm.","directories":{},"sideEffects":false,"_nodeVersion":"23.1.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","vitest":"^3.2.4","typescript":"^5.9.2","@types/node":"^24.3.1"},"_npmOperationalInternal":{"tmp":"tmp/color-matcher_1.0.0_1757526277719_0.9070084186060434","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@a.r.i_eze/color-matcher","version":"1.0.3","keywords":["color","lab","deltaE","nearest-color","color-matcher","hex","rgb","converter"],"author":{"name":"A.R.I Eze"},"license":"MIT","_id":"@a.r.i_eze/color-matcher@1.0.3","maintainers":[{"name":"a.r.i_eze","email":"kingsley2169@icloud.com"}],"homepage":"https://github.com/kingsley2169/color-matcher#readme","bugs":{"url":"https://github.com/kingsley2169/color-matcher/issues"},"dist":{"shasum":"02ed92a00d5f8db28d08650311a741adc0134c9c","tarball":"https://registry.npmjs.org/@a.r.i_eze/color-matcher/-/color-matcher-1.0.3.tgz","fileCount":8,"integrity":"sha512-91tG5zBnfXkDP1/BRht/UOLLk+4oj+44IcujO6/tZoLJktq61xv+usGoWf2zDJSsr1KN4h+UuNBltsDQUybOAw==","signatures":[{"sig":"MEQCHxW9i3SqZ9DbmtXvo6usrGEgPpKJER/pWGoKREfNCPsCIQCJ5G1hWsMvjlHBtlGzxomI9oIc9GjjK/2WlP8Uhd+96Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":109063},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"}},"gitHead":"b89471f91ffea086f3f3f2afccb36da7212fe02a","scripts":{"test":"vitest","build":"tsup","prepublishOnly":"npm run build"},"_npmUser":{"name":"a.r.i_eze","email":"kingsley2169@icloud.com"},"repository":{"url":"git+https://github.com/kingsley2169/color-matcher.git","type":"git"},"_npmVersion":"11.5.2","description":"A module to find the closest human-readable name for any color using Lab color space and Delta-E algorithm.","directories":{},"sideEffects":false,"_nodeVersion":"23.1.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","vitest":"^3.2.4","typescript":"^5.9.2","@types/node":"^24.3.1"},"_npmOperationalInternal":{"tmp":"tmp/color-matcher_1.0.3_1757534933605_0.8104148233856254","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@a.r.i_eze/color-matcher","version":"1.0.4","keywords":["color","lab","deltaE","nearest-color","color-matcher","hex","rgb","converter"],"author":{"name":"A.R.I Eze"},"license":"MIT","_id":"@a.r.i_eze/color-matcher@1.0.4","maintainers":[{"name":"a.r.i_eze","email":"kingsley2169@icloud.com"}],"homepage":"https://github.com/kingsley2169/color-matcher#readme","bugs":{"url":"https://github.com/kingsley2169/color-matcher/issues"},"dist":{"shasum":"6bf557620a414387b5f4ec14f7c6276382f0b2cd","tarball":"https://registry.npmjs.org/@a.r.i_eze/color-matcher/-/color-matcher-1.0.4.tgz","fileCount":8,"integrity":"sha512-3Pckprvw8rCXWR8v56jMQSndWjP2lR8o4tm7e9Qdk3I9umNHIq8rp3CafgmNChuU3m3cM4FLWppEdIvPuewf5A==","signatures":[{"sig":"MEQCIDn7RVH0UmE9yiEbhdqooz0/rrMKVX8QgtrYumfXVusUAiA4ncHQ4KnENoagDqOvxkjRIjGOdLrK3tqI13ZTU9samQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":109061},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"b89471f91ffea086f3f3f2afccb36da7212fe02a","scripts":{"test":"vitest","build":"tsup","prepublishOnly":"npm run build"},"_npmUser":{"name":"a.r.i_eze","email":"kingsley2169@icloud.com"},"repository":{"url":"git+https://github.com/kingsley2169/color-matcher.git","type":"git"},"_npmVersion":"11.5.2","description":"A module to find the closest human-readable name for any color using Lab color space and Delta-E algorithm.","directories":{},"sideEffects":false,"_nodeVersion":"23.1.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","vitest":"^3.2.4","typescript":"^5.9.2","@types/node":"^24.3.1"},"_npmOperationalInternal":{"tmp":"tmp/color-matcher_1.0.4_1757535945920_0.9970177043199182","host":"s3://npm-registry-packages-npm-production"}},"1.0.5":{"name":"@a.r.i_eze/color-matcher","version":"1.0.5","keywords":["color","lab","deltaE","nearest-color","color-matcher","hex","rgb","converter"],"author":{"name":"A.R.I Eze"},"license":"MIT","_id":"@a.r.i_eze/color-matcher@1.0.5","maintainers":[{"name":"a.r.i_eze","email":"kingsley2169@icloud.com"}],"homepage":"https://github.com/kingsley2169/color-matcher#readme","bugs":{"url":"https://github.com/kingsley2169/color-matcher/issues"},"dist":{"shasum":"77598bdc0343179e3db77a54985c6c8814a7f026","tarball":"https://registry.npmjs.org/@a.r.i_eze/color-matcher/-/color-matcher-1.0.5.tgz","fileCount":8,"integrity":"sha512-YrkoTPc45cKfZa6298N6FH6cGxdiLOdCLIS2jj9wK34w+4hlZiJOKNQU8Y52AIqe//cYpoFnrfiZAFd+yGvxIA==","signatures":[{"sig":"MEQCIHdaWVXyP/Uyvyl3g6CQYAeHfQhznH1YsEAyxAX49iWEAiBR52TwdCI3Q+B5aGORvm9J3PVj4oGNOrZ33j5hh6JJzQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":114468},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"5199e927190d8cd3b751512feea9d0d253950680","scripts":{"test":"vitest","build":"tsup","prepublishOnly":"npm run build"},"_npmUser":{"name":"a.r.i_eze","email":"kingsley2169@icloud.com"},"repository":{"url":"git+https://github.com/kingsley2169/color-matcher.git","type":"git"},"_npmVersion":"11.5.2","description":"A module to find the closest human-readable name for any color using Lab color space and Delta-E algorithm.","directories":{},"sideEffects":false,"_nodeVersion":"23.1.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","vitest":"^3.2.4","typescript":"^5.9.2","@types/node":"^24.3.1"},"_npmOperationalInternal":{"tmp":"tmp/color-matcher_1.0.5_1757538107073_0.038989626288598034","host":"s3://npm-registry-packages-npm-production"}},"1.0.6":{"name":"@a.r.i_eze/color-matcher","version":"1.0.6","keywords":["color","lab","deltaE","nearest-color","color-matcher","hex","rgb","converter"],"author":{"name":"A.R.I Eze"},"license":"MIT","_id":"@a.r.i_eze/color-matcher@1.0.6","maintainers":[{"name":"a.r.i_eze","email":"kingsley2169@icloud.com"}],"homepage":"https://github.com/kingsley2169/color-matcher#readme","bugs":{"url":"https://github.com/kingsley2169/color-matcher/issues"},"dist":{"shasum":"123c84eecf2fac7ed2f27a56f1a6ab6d8caf96db","tarball":"https://registry.npmjs.org/@a.r.i_eze/color-matcher/-/color-matcher-1.0.6.tgz","fileCount":8,"integrity":"sha512-1J4xRXMXl88wTUnvbAZnfz+c1shBkqzhI/jbS09/ju1TKFNPyl0gtOZgjVaBIfHk3tvouLBk+1oO+AHPWPaJRg==","signatures":[{"sig":"MEUCIAM3c02Io9QKqGNTYZSZQhY5avjGSy0oEaNL/GAPHk9NAiEAmjipikFtr5OoEARo7BY/ISW2RyiE6sVxmSkCDXFTIe4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":114275},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"gitHead":"2144de86698d8e44de2d925a21c3d067050216d5","scripts":{"test":"vitest","build":"tsup","prepublishOnly":"npm run build"},"_npmUser":{"name":"a.r.i_eze","email":"kingsley2169@icloud.com"},"repository":{"url":"git+https://github.com/kingsley2169/color-matcher.git","type":"git"},"_npmVersion":"11.5.2","description":"A module to find the closest human-readable name for any color using Lab color space and Delta-E algorithm.","directories":{},"sideEffects":false,"_nodeVersion":"23.1.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","vitest":"^3.2.4","typescript":"^5.9.2","@types/node":"^24.3.1"},"_npmOperationalInternal":{"tmp":"tmp/color-matcher_1.0.6_1757539296054_0.7661550202786684","host":"s3://npm-registry-packages-npm-production"}},"1.0.7":{"name":"@a.r.i_eze/color-matcher","version":"1.0.7","description":"A module to find the closest human-readable name for any color using Lab color space and Delta-E algorithm.","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"require":"./dist/index.cjs","import":"./dist/index.js","types":"./dist/index.d.ts"}},"repository":{"type":"git","url":"git+https://github.com/kingsley2169/color-matcher.git"},"bugs":{"url":"https://github.com/kingsley2169/color-matcher/issues"},"homepage":"https://github.com/kingsley2169/color-matcher#readme","sideEffects":false,"scripts":{"prepublishOnly":"npm run build","build":"tsup","test":"vitest"},"type":"module","keywords":["color","lab","deltaE","nearest-color","color-matcher","hex","rgb","converter"],"author":{"name":"A.R.I Eze"},"license":"MIT","devDependencies":{"@types/node":"^24.3.1","tsup":"^8.5.0","typescript":"^5.9.2","vitest":"^3.2.4"},"_id":"@a.r.i_eze/color-matcher@1.0.7","gitHead":"eba7f1e65c1deb7148da50276150932677227b79","_nodeVersion":"23.1.0","_npmVersion":"11.5.2","dist":{"integrity":"sha512-wApyUkMTlrneAeTj6QjP/bWfYycBL3KT5jPCtc5kYxC4ZW8+ggKzFUkXgesgj5KRw5s3dsnWUux80nLkdbE7eA==","shasum":"d9daf200a1106e20bc8be74bfebf1b1ddcbd6780","tarball":"https://registry.npmjs.org/@a.r.i_eze/color-matcher/-/color-matcher-1.0.7.tgz","fileCount":8,"unpackedSize":117990,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCeawZZzniuScNLoZ7GqU9nL+SJxKTnCPanD+Sysq+ReQIgRxWvBMwqXxiZoKVLdObPEsaJXI+fqthXUNdY5CXO5vo="}]},"_npmUser":{"name":"a.r.i_eze","email":"kingsley2169@icloud.com"},"directories":{},"maintainers":[{"name":"a.r.i_eze","email":"kingsley2169@icloud.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/color-matcher_1.0.7_1757539504203_0.5107717259692317"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-10T17:44:37.612Z","modified":"2025-09-10T21:25:04.642Z","1.0.0":"2025-09-10T17:44:37.892Z","1.0.3":"2025-09-10T20:08:53.793Z","1.0.4":"2025-09-10T20:25:46.121Z","1.0.5":"2025-09-10T21:01:47.285Z","1.0.6":"2025-09-10T21:21:36.265Z","1.0.7":"2025-09-10T21:25:04.476Z"},"bugs":{"url":"https://github.com/kingsley2169/color-matcher/issues"},"author":{"name":"A.R.I Eze"},"license":"MIT","homepage":"https://github.com/kingsley2169/color-matcher#readme","keywords":["color","lab","deltaE","nearest-color","color-matcher","hex","rgb","converter"],"repository":{"type":"git","url":"git+https://github.com/kingsley2169/color-matcher.git"},"description":"A module to find the closest human-readable name for any color using Lab color space and Delta-E algorithm.","maintainers":[{"name":"a.r.i_eze","email":"kingsley2169@icloud.com"}],"readme":"# color-matcher\n\n[![npm version](https://badge.fury.io/js/%40a.r.i_eze%2fcolor-matcher.svg)](https://badge.fury.io/js/%40a.r.i_eze%2fcolor-matcher)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA lightweight and performant JavaScript/TypeScript library to find the nearest color from a predefined list. It supports multiple color difference algorithms (CIE76, CIE94, CIEDE2000) for perceptually accurate comparisons.\n\n## Features\n\n-   **Fast and Accurate**: Uses pre-calculated Lab color values for high performance.\n-   **Multiple Algorithms**: Supports CIE76, CIE94, and the industry-standard CIEDE2000 for superior perceptual accuracy.\n-   **Flexible**: Use the built-in color list or provide your own custom palette.\n-   **Rich Information**: Returns the matched color's name, hex code, and the calculated color difference.\n-   **TypeScript Ready**: Written in TypeScript with full type definitions.\n\n## Installation\n\n```bash\n# npm\nnpm install @a.r.i_eze/color-matcher\n\n# yarn\nyarn add @a.r.i_eze/color-matcher\n\n# pnpm\npnpm add @a.r.i_eze/color-matcher\n```\n\n## Use Cases\n\n`color-matcher` can be useful in a variety of applications:\n\n-   **E-commerce**: Tag products with the closest standard color name (e.g., \"Crimson Red\" for a t-shirt), improving search and filtering for customers.\n-   **Data Visualization**: Automatically assign meaningful color names to data points in charts, graphs, and maps for better readability.\n-   **Design Systems & Theming**: Map brand colors to a standard color palette, ensuring consistency and helping developers find the right color name.\n-   **Accessibility Tools**: Help users with color vision deficiencies by providing the nearest standard color name for any given color.\n-   **Image Analysis**: Extract dominant colors from an image and give them human-readable names.\n\n## Usage\n\n### Basic Usage\n\nThe `findNearestColor` function is the primary entry point. It takes a hex color string and returns the closest match from its internal color list.\n\n```javascript\nimport { findNearestColor } from 'color-matcher';\n\nconst match = findNearestColor('#FF1000');\n\nif (match) {\n  console.log(match.name);     // \"Red (Web)\"\n  console.log(match.hex);      // \"#FF0000\"\n  console.log(match.distance); // A small number indicating the difference\n}\n```\n\n### Using Different Delta E Formulas\n\nThe library defaults to the basic `CIE76` formula. For more perceptually uniform results, you can specify `CIE94` or the recommended `CIEDE2000`.\n\n```javascript\nimport { findNearestColor } from 'color-matcher';\n\n// Using CIEDE2000 (recommended for best accuracy)\nconst match2000 = findNearestColor('#008081', { formula: '2000' });\nconsole.log(match2000.name); // \"Teal\"\n\n// Using CIE94\nconst match94 = findNearestColor('#008081', { formula: '94' });\nconsole.log(match94.name); // \"Teal\"\n```\n\n### Using a Custom Color Palette\n\nYou can provide your own list of colors. For the best performance, pre-calculate the Lab values for your custom list using the exported utility functions.\n\n```javascript\nimport { findNearestColor, rgbToLab, hexToRgb } from 'color-matcher';\n\nconst myPalette = [\n  { name: 'My Brand Red', hex: '#D92027' },\n  { name: 'My Brand Blue', hex: '#1B98E0' },\n  { name: 'My Brand Green', hex: '#4CAF50' },\n];\n\n// For best performance, pre-calculate Lab values\nconst myPaletteWithLab = myPalette.map(color => ({\n  ...color,\n  lab: rgbToLab(hexToRgb(color.hex))\n}));\n\nconst match = findNearestColor('#E0252C', {\n  colorList: myPaletteWithLab,\n  formula: '2000'\n});\n\nconsole.log(match.name); // \"My Brand Red\"\n```\n\n## API Reference\n\n### `findAllClosestColors(inputHex, options?)`\n\nFinds a list of colors that are close to the input color. Returns an array of `ColorMatch` objects, sorted by distance (closest first).\n\n-   `inputHex: string`: The color to match, as a hex string (e.g., `#RRGGBB`).\n-   `options?: FindAllClosestColorsOptions`:\n    -   `count?: number`: The number of closest colors to return. Defaults to `5`. This option is ignored if `threshold` is set.\n    -   `threshold?: number`: The maximum distance for a color to be considered \"close\". If set, this option takes precedence over `count`.\n    -   `formula?: '76' | '94' | '2000'`: The Delta E formula to use. Defaults to `'76'`.\n    -   `colorList?: ColorWithLab[]`: A custom array of colors to match against.\n\n#### Example\n\n```javascript\nimport { findAllClosestColors } from 'color-matcher';\n\n// Get the top 3 closest colors\nconst top3 = findAllClosestColors('#FF1A00', { count: 3, formula: '2000' });\nconsole.log(top3);\n\n// Get all colors within a distance of 10\nconst withinThreshold = findAllClosestColors('#008081', { threshold: 10, formula: '2000' });\nconsole.log(withinThreshold.map(c => c.name));\n```\n\n### `findNearestColor(inputHex, options?)`\n\n-   `inputHex: string`: The color to match, as a hex string (e.g., `#RRGGBB` or `RRGGBB`).\n-   `options?: FindNearestColorOptions`:\n    -   `formula?: '76' | '94' | '2000'`: The Delta E formula to use. Defaults to `'76'`.\n    -   `colorList?: ColorWithLab[]`: A custom array of colors to match against. Defaults to the built-in `ColorListWithLab`.\n\nReturns a `ColorMatch` object, or `null` if no match is found (e.g. with an empty `colorList`). Throws an error if the input color format is invalid.\n\n### `ColorMatch` Type\n\nThe object returned by `findNearestColor`.\n\n```typescript\ninterface ColorMatch {\n  name: string;     // Name of the matched color\n  hex: string;      // Hex code of the matched color\n  distance: number; // Calculated color difference (lower is closer)\n}\n```\n\n### Color Lists\n\n-   `ColorList: Color[]`: The default list of colors, each with a `name` and `hex` property.\n-   `getColorListWithLab(): ColorWithLab[]`: A function that returns the default list with pre-calculated `lab` values. The result is memoized.\n\n### Delta E Functions\n\nYou can also use the Delta E functions directly if you have Lab color values.\n\n-   `deltaE76(lab1: Lab, lab2: Lab): number`\n-   `deltaE94(lab1: Lab, lab2: Lab): number`\n-   `deltaE2000(lab1: Lab, lab2: Lab): number`\n\n### Color Conversion Utilities\n\nThe library exports several color conversion utilities: `hexToRgb`, `rgbToLab`, `rgbToXyz`, and `xyzToLab`.\n\n## Contributing\n\nContributions are welcome! Whether you're fixing a bug, adding a feature, or improving documentation, your help is appreciated.\n\nTo contribute, please follow these steps:\n\n1.  **Fork the repository** and create your branch from `main`.\n2.  **Run `npm install`** to set up the development environment.\n3.  **Make your changes** and add tests for them.\n4.  **Ensure the test suite passes** with `npm test`.\n5.  **Submit a pull request** with a clear description of your changes.\n\n## License\n\nMIT","readmeFilename":"README.md"}