Alexandro.Net

Download README · GitHub release

@stackline/color

A tiny, framework-agnostic color picker foundation for modern web applications.

npm version license GitHub repository Docs Reddit community

Documentation | npm | Issues | Repository

Current package version: 1.0.4

Why this package?

@stackline/color is maintained as part of the Stackline package collection.

Compatibility

Item Value
Package @stackline/color@1.0.4
API target See the package-specific API reference
Supported Node.js See supported framework requirements
License MIT
Module type module
Main entry ./dist/index.cjs
Module entry ./dist/index.js
Types ./dist/index.d.ts
Runtime dependencies none

Installation

npm install @stackline/color

Usage and API reference

A maintained framework-agnostic color picker foundation for modern web applications, with a precise TypeScript color engine, a lightweight vanilla UI layer, and a documentation site centered on a live playground.

Documentation & Playground | npm | GitHub Download | Issues | Repository

Latest version: 1.0.4

Why this library?

Most color picker packages solve the visible UI, but not always the long-term foundation:

@stackline/color is built as a clean TypeScript-first foundation package. The core stays framework-agnostic, the vanilla DOM layer stays light, and future React, Vue, and Angular wrappers can reuse the same engine instead of replacing it.

Version 1.0.2 keeps that stable API while making functional color parsing linear and updating package documentation and GitHub release tooling.

Features

Feature Supported
TypeScript-first core library ✅
Framework-agnostic runtime ✅
ESM + CJS + bundled types ✅
Zero runtime dependencies ✅
2D saturation/value area ✅
Hue slider ✅
Alpha slider ✅
HEX, RGB, HSL, and HSV input support ✅
Rich normalized color snapshots ✅
Keyboard and pointer interaction ✅
CSS variable theming ✅
Mobile-friendly pointer events ✅
Documentation site with live playground ✅
Future wrapper-ready architecture ✅

Table of Contents

  1. Installation
  2. Direct Download
  3. Quick Start
  4. API Overview
  5. Color Snapshot Output
  6. Customization
  7. Accessibility and Interaction
  8. Documentation and Playground
  9. Run Locally
  10. Security
  11. Community and Links
  12. License

Installation

npm install @stackline/color

Direct Download

If you prefer plain JavaScript instead of npm, download the browser bundle from GitHub:

The archive includes color.browser.js and exposes window.StacklineColor.

<div id="picker"></div>
<script src="./color.browser.js"></script>
<script>
  const picker = StacklineColor.createColorPicker({
    el: "#picker",
    color: "#7c3aed",
    hue: true,
    alpha: true
  });

  console.log(picker.getColor().hex);
</script>

Quick Start

import { createColorPicker } from "@stackline/color";

const picker = createColorPicker({
  el: "#picker",
  color: "#7c3aed",
  hue: true,
  alpha: true,
  onChange: (color) => {
    console.log(color.hex, color.rgb, color.hsl);
  }
});

API Overview

The package is centered around a small public surface:

import {
  createColorPicker,
  createColorSnapshot,
  formatColor,
  parseColor
} from "@stackline/color";

Core runtime capabilities:

Useful core helpers:

Color Snapshot Output

Every color change returns a normalized snapshot:

{
  hex: "#7c3aed",
  hexa: "#7c3aedff",
  rgb: { r: 124, g: 58, b: 237 },
  rgba: { r: 124, g: 58, b: 237, a: 1 },
  hsl: { h: 262, s: 83, l: 58 },
  hsla: { h: 262, s: 83, l: 58, a: 1 },
  hsv: { h: 262, s: 76, v: 93 },
  hsva: { h: 262, s: 76, v: 93, a: 1 },
  alpha: 1
}

Customization

The default UI is intentionally minimal and controlled through CSS variables.

Size is customizable too, so the picker can scale from compact utility usage to roomier settings panels.

.my-picker {
  --rv-color-max-width: 360px;
  --rv-color-panel-height: 256px;
  --rv-color-slider-height: 18px;
  --rv-color-handle-size: 20px;
  --rv-color-line-handle-width: 16px;
  --rv-color-line-handle-height: 26px;
  --rv-color-radius: 18px;
  --rv-color-focus: #0f766e;
  --rv-color-surface: #f8fafc;
}

If you prefer to manage styles yourself, disable auto-injection:

createColorPicker({
  el: "#picker",
  injectStyles: false
});

Then inject the exported base styles manually:

import { COLOR_PICKER_STYLES } from "@stackline/color";

Accessibility and Interaction

The vanilla picker already ships with practical defaults:

Documentation and Playground

The docs site includes:

Docs: https://alexandro.net/docs/vanilla/color/

Run Locally

npm install
npm run build:all

Verification:

npm run typecheck
npm test

Minimal browser example:

Security

Report vulnerabilities privately by following SECURITY.md. Do not disclose exploit details in a public issue.

Community and Links

Use the repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline to share examples, ask usage questions, and discuss releases.

License

MIT

Credits and original authors

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.