Swatchify — Extract Dominant Colors from Images

SWATCH IFY

Extract Dominant Colors From Images

◆ NPM PACKAGE ◆ BROWSER-ONLY ◆ REST API ◆ GO LIBRARY ◆ CLI TOOL ◆ K-MEANS CLUSTERING ◆ JSON OUTPUT ◆ PALETTE PNG ◆ CROSS-PLATFORM ◆ OPEN SOURCE ◆ ◆ NPM PACKAGE ◆ BROWSER-ONLY ◆ REST API ◆ GO LIBRARY ◆ CLI TOOL ◆ K-MEANS CLUSTERING ◆ JSON OUTPUT ◆ PALETTE PNG ◆ CROSS-PLATFORM ◆ OPEN SOURCE ◆

GET IT NOW

Go Install

go install github.com/james-see/swatchify@latest

Homebrew

brew install james-see/tap/swatchify

Download Binary

→ github.com/james-see/swatchify/releases

★ GITHUB DOWNLOAD

BROWSER-ONLY JS

NPM Install — Client-Side Color Extraction

npm install swatchme

swatchme is a zero-dependency JavaScript/TypeScript library for extracting dominant colors from images entirely in the browser. No server required. Uses the same k-means++ clustering algorithm as the Go version. ~2KB gzipped.

import { extractColors, generatePaletteCanvas } from 'swatchme';


const file = document.querySelector('input[type="file"]').files[0];
const colors = await extractColors(file, {
  numColors: 6,
  excludeWhite: true
});

// → [{ hex: "#4A90D9", percentage: 32.5, rgb: {r,g,b} }, ...]


const canvas = generatePaletteCanvas(colors, 500, 100);
document.body.appendChild(canvas);

🌐

BROWSER ONLY

100% client-side. No server calls. Works offline.

📦

ZERO DEPS

No runtime dependencies. ~2KB gzipped.

🔌

ANY INPUT

File, Blob, Image, Canvas, ImageData, or URL.

📝

TYPESCRIPT

Full TypeScript support with exported types.

NPM PACKAGE JS SOURCE

HOW IT WORKS

$ swatchify photo.jpg
#131014
#7673AD
#73500A
#B68296
#44353B

$ swatchify logo.png -n 8 --json
{
  "image": "logo.png",
  "colors": [
    {"hex": "#FF0000", "percentage": 34.5},
    {"hex": "#00FF00", "percentage": 21.0},
    ...
  ]
}

$ swatchify brand.png --png palette.png --show
→ Opens palette image with hex labels

EXAMPLE PALETTE OUTPUT:

#131014

#7673AD

#73500A

#B68296

#44353B

FEATURES

🌐

REST API SERVER

Run as HTTP server. POST images, get JSON colors back. CORS enabled.

📦

GO LIBRARY

Import as a package. ExtractFromFile(), ExtractFromImage(), GeneratePalette().

🟨

NPM PACKAGE

Browser-only JavaScript library. Zero deps, ~2KB gzipped. npm install swatchme

⚡

BLAZING FAST

Sub-300ms processing. Automatic image downscaling for speed.

🎯

K-MEANS++

Advanced clustering algorithm for accurate dominant color extraction.

📊

JSON OUTPUT

Machine-readable output with hex values and percentage weights.

🎨

PALETTE PNG

Generate visual palettes with proportional color blocks and hex labels.

🔧

FILTERS

Exclude white, black, or similar colors. Control minimum contrast.

💻

CROSS-PLATFORM

Single binary for macOS, Linux, and Windows. ARM64 supported.

SUPPORTED FORMATS

JPEG PNG WebP GIF BMP TIFF

API SERVER

$ swatchify serve --port 8080
🎨 Swatchify server starting on http://localhost:8080

$ curl -X POST -F "image=@photo.jpg" localhost:8080/extract
{
  "success": true,
  "colors": [
    {"hex": "#FF0000", "percentage": 34.5},
    {"hex": "#00FF00", "percentage": 21.0}
  ]
}

$ curl -X POST -F "image=@photo.jpg" -F "colors=8" \
     -F "exclude_white=true" localhost:8080/extract

GO LIBRARY

import "github.com/james-see/swatchify/pkg/swatchify"

// Extract colors from file
colors, err := swatchify.ExtractFromFile("photo.jpg", nil)

// With options
opts := &swatchify.Options{
    NumColors:    8,
    ExcludeWhite: true,
}
colors, _ := swatchify.ExtractFromFile("photo.jpg", opts)

// Generate palette
swatchify.GeneratePalette(colors, "palette.png", nil)

CLI FLAGS

-n, --colors     Number of colors (default: 5)
--json           Output as JSON
--png            Generate palette PNG
--exclude-white  Skip near-white colors
--exclude-black  Skip near-black colors
--min-contrast   Min distance between colors
--show           Open palette after creation
--quality        0-100, accuracy vs speed
--width          Palette width (default: 1000)
--height         Palette height (default: 200)

serve --port     Start API server on port