@lostelk/nearest-color

English · 简体中文

Find the nearest color in a given color palette. ✨

Suitable for both browser and Node environments.

Getting Started

Using in Node and Browser

1.Install

• Install as an npm dependency

  $ npm i @lostelk/nearest-color

• Load from CDN

  <script src="https://unpkg.com/@lostelk/nearest-color"></script>

2.Import

• CommonJS

  const NearestColor = require('@lostelk/nearest-color');

• ES Module

  import NearestColor from '@lostelk/nearest-color';

3.Use

• Find the nearest color - Default Color Palette

  Use the find method to find the nearest color in the default color palette. (Supports Hex, RGB, HSL, HSV)

  const findNearestColor = new NearestColor();
  
  const result = findNearestColor.find('#f0f0f6');

  Result

  {
    category: "white",
    key: "#f5f5f5",
    english: ["whitesmoke", "white"],
    chinese: ["烟白色", "白色"],
    distance: 7.14142842854285
  }

• Find the nearest color - Custom Color Palette

  Import a custom color palette through the constructor or the from method.

  const CUSTOM_PALETTE = [
    {
      key: '#3498db',
      name: ['Blue'],
    },
    {
      key: '#e74c3c',
      name: ['Red'],
    },
    {
      key: '#27ae60',
      name: ['Green'],
    },
    // Add more colors...
  ];

  // Import a custom color palette through the constructor
  const nearestColor = new NearestColor(CUSTOM_PALETTE);
  
  // Or import through the `from` method
  const nearestColor = NearestColor.from(CUSTOM_PALETTE);
  
  const result = nearestColor.find('#2563eb');

  Result

  {
    key: '#3498db',
    name: ['Blue'],
    distance: 57.358521598799946
  }
  

• Find the nearest color - Add Additional Colors to the Existing Palette

  Use the concat method to add additional colors to the existing color palette

  const ADDITIONAL_PALETTE = [
    {
      key: '#ffcc00',
      names: ['Yellow'],
    },
    {
      key: '#9900cc',
      names: ['Purple'],
    },
    // Add more colors...
  ];

  const nearestColor = new NearestColor();
  
  const nearestColorNew = nearestColor.concat(ADDITIONAL_PALETTE);
  
  const result = nearestColorNew.find('#e0b60f');

  Result

  {
    key: '#ffcc00',
    names: [ 'Yellow' ],
    distance: 40.8656334834051
  }

API

new NearestColor(colorPalette)

Create a new instance of the NearestColor class.

colorPalette - colorPalette is an optional parameter, an array containing color objects, serving as a custom color palette.

find(color)

Returns：{ key: Any, distance: Number，... }

Method to find the nearest color.

color - Color to match, supports Hex, RGB, HSL, and HSV formats.

returns - Contains information related to the nearest color, such as color key-value pairs and distance.

from(colorPalette)

Returns：new NearestColor(colorPalette)

Create a NearestColor instance using a custom color palette.

colorPalette - Array containing key-value pairs of colors, serving as a custom color palette.

returns - New NearestColor instance based on the provided custom color palette.

concat(newColorPalette)

Returns：new NearestColor({...oldColorPalette, ...newColorPalette})

Add additional colors to the existing color palette and create a new NearestColor instance.

newColorPalette - Array containing additional color key-value pairs, representing colors to be added to the current palette.

returns - New NearestColor instance containing the extended color palette.