hex-to-css-filter-library v2.0.0

hex-to-css-filter-library

A JavaScript library to access a remote database of CSS filters to change HTML elements to any hex color code.

Usage

1. Install the dependency

   • NPM: npm install hex-to-css-filter-library
   • Yarn: yarn add hex-to-css-filter-library

2. Add the dependency into your file

   import HexToCssFilterLibrary from 'hex-to-css-filter-library'

3. Create an account with DBHub.io

4. Generate a new API key on your Settings page

5. Use your API key to fetch a CSS filter or query the database

   const filter = await new HexToCssFilterLibrary(apiKey).fetchFilter('#42dead')

Documentation

Hex Color Input

Hex color codes can be passed in with 3 or 6 digits, case insensitive, and hash insensitive.

For example, all of these are valid and accepted representations:

• 333
• #333
• 333333
• #333333

Constructor

// This is hardcoded but it's standard to set this as an environment variable
// Your key should be kept secret and not committed or made public
const apiKey = '...'
const hexToCssFilterLibrary = new HexToCssFilterLibrary(apiKey)

const options = {...}
const hexToCssFilterLibrary = new HexToCssFilterLibrary(apiKey, options)

Options

Starting with 2.0.0, this package relies on Node 18's experimental fetch API instead of node-fetch. This makes the package work in the browser and Node.

For Node usage, if not on 18 or not wanting to rely on an experimental feature, feel free to import node-fetch or another dependency and pass in the relevant options.

import fetch, { FormData, Headers, Request } from 'node-fetch'

const options = {
  formDataClass: FormData,
  headersClass: Headers,
  requestClass: Request,
  fetchFunction: fetch,
}
const hexToCssFilterLibrary = new HexToCssFilterLibrary(apiKey, options)

Fetch Filter

const filter = await hexToCssFilterLibrary.fetchFilter('#42dead')
// invert(66%) sepia(56%) saturate(416%) hue-rotate(110deg) brightness(98%) contrast(100%)

const options = {
  filterPrefix: true,
  preBlacken: true
}
const filter = await hexToCssFilterLibrary.fetchFilter('#42dead', options)
// filter: brightness(0) saturate(1) invert(66%) sepia(56%) saturate(416%) hue-rotate(110deg) brightness(98%) contrast(100%)

Options

Fetch Color Record

const colorRecord = await hexToCssFilterLibrary.fetchColorRecord('#42dead')
// {
//   id: 4382381,
//   invert: 66,
//   sepia: 56,
//   saturate: 416,
//   'hue-rotate': 110,
//   brightness: 98,
//   contrast: 100,
//   loss: 0.2578769732
// }

const options = { raw: true }
const rawColorRecord = await hexToCssFilterLibrary.fetchColorRecord('#42dead', options)
// [
//   [
//     { Name: 'id', Type: 4, Value: '4382381' },
//     { Name: 'invert', Type: 4, Value: '66' },
//     { Name: 'sepia', Type: 4, Value: '56' },
//     { Name: 'saturate', Type: 4, Value: '416' },
//     { Name: 'hue-rotate', Type: 4, Value: '110' },
//     { Name: 'brightness', Type: 4, Value: '98' },
//     { Name: 'contrast', Type: 4, Value: '100' },
//     { Name: 'loss', Type: 5, Value: '0.2578769732' }
//   ]
// ]

Options

Query DB

const sql = 'SELECT COUNT() FROM color'
const response = await hexToCssFilterLibrary.queryDb(sql)
// [ [ { Name: 'COUNT()', Type: 4, Value: '16777216' } ] ]

const options = { getFirstValue: true }
const response = await hexToCssFilterLibrary.queryDb(sql, options)
// 16777216

Options

FAQ

• A filter isn't working/accurate, what's going on?

  • The filters in the database assume a starting color of black (#000000). If your HTML element isn't black, you'll need to use the preBlacken option.

• What if I'm not using JavaScript?

  • DBHub.io has Python and Go libraries which can also be used to access the database.

• What if I don't want to rely on your DBHub.io database?

  • There's a few options...

    • Use the sister package, hex-to-css-filter-library-with-db, which calls a local copy of the database.

    • The database has a CC-BY-4.0 license so feel free to fork it on DBHub.io or host elsewhere. It's approximately 524 MB and you can use the constructor options to change the DBHub.io default values.

About Problem Domain

The current leading method to convert a hex color to a CSS filter is through trial & error with loss minimization.

• Search using SPSA by MultiplyByZer0 on Stack Overflow

• NPM package: hex-to-css-filter

• Brute force with partial color coverage by Dave on Stack Overflow

Instead of spending your own time & resources doing this, you can use this library to lookup already calculated low loss values. Currently all colors have less than 1% loss.

I don't have plans to process lower values due to diminishing returns. If you are interested in doing this though, please get in touch and I can share my code.

Database

There are 16,777,216 RGB hex colors. This is equal to 2563, with 256 values for red, green, and blue.

For reference: SQLite datatypes

Loss Statistics

pie showData
  "0% loss" : 8
  "0.0% loss" : 1233492
  "0.1% loss" : 2944170
  "0.2% loss" : 3259251
  "0.3% loss" : 2388299
  "0.4% loss" : 1716667
  "0.5% loss" : 1323179
  "0.6% loss" : 1106540
  "0.7% loss" : 987981
  "0.8% loss" : 920722
  "0.9% loss" : 896907