Kolory

Paint your projects with vibrant Kolory

Overview

Kolory is a lightweight, versatile, and zero-dependency JavaScript library designed for seamless color manipulation and exploration. It supports multiple color formats (HEX, RGB, RGBA, HSL, HSLA) and provides built-in ANSI escape code support for styling terminal output. With a simple and intuitive API, Kolory empowers developers to work with colors effortlessly in both Node.js and browser environments.

Whether you're converting colors, generating dynamic palettes, or enhancing CLI output with vibrant formatting, Kolory is your go-to tool for all things color.

Features

• Multiple Color Formats: Work with HEX, RGB, RGBA, HSL, and HSLA formats effortlessly.
• Prebuilt Distributions: Available in ESM, CommonJS, and IIFE formats for maximum compatibility.
• Zero Dependencies: Lightweight with a minimal footprint for optimal performance.
• TypeScript Support: First-class TypeScript definitions for a type-safe development experience.
• Cross-Platform: Compatible with Node.js, Deno, and modern browsers.
• ANSI Styling: Built-in support for 4-bit, 8-bit, and 24-bit ANSI escape codes to style CLI output.

Installation

Kolory can be installed via all major package managers or used directly in the browser via a CDN.

Using Package Managers

# npm
npm install kolory

# yarn
yarn add kolory

# pnpm
pnpm add kolory

# bun
bun add kolory

Using CDN (Browser)

Include Kolory in your HTML for browser-based projects:

<!-- UNPKG -->
<script src="https://unpkg.com/kolory/dist/index.iife.js"></script>

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/kolory/dist/index.iife.js"></script>

<!-- ESM (Modern Browsers) -->
<script type="module">
  import kolory from 'https://esm.sh/kolory';
</script>

Usage

Kolory provides a straightforward API to access and manipulate colors in various formats. Below are examples for different environments.

ESM (Modern JavaScript)

import kolory, { hex, rgb, rgba, hsl, hsla } from 'kolory';

console.log(kolory.hex.blue_metal);
console.log(hex.blue_metal);
console.log(rgb.blue_metal);

CommonJS

const { hex, rgb } = require('kolory');

console.log(hex.sunset_orange);
console.log(rgb.sunset_orange);

Browser (IIFE via CDN)

<script src="https://unpkg.com/kolory/dist/index.iife.js"></script>
<script>
  console.log(kolory.hex.blue_metal);
</script>

Color Data Structure

Kolory organizes colors in a structured JSON format, with each color entry providing values for all supported formats. Below is an example:

{
  "blue_metal": {
    "hex": "#4A90E2",
    "rgb": "74,144,226",
    "rgba": "74,144,226,1",
    "hsl": "210,73%,58%",
    "hsla": "210,73%,58%,1"
  }
}

API Reference

Kolory exports several modules to access colors in different formats:

| Export | Description | | -------- | ---------------------------------------------- | | kolory | Structured object containing all color formats | | hex | Colors in HEX format (e.g., #4A90E2) | | rgb | Colors in RGB format (e.g., 74,144,226) | | rgba | Colors in RGBA format (e.g., 74,144,226,1) | | hsl | Colors in HSL format (e.g., 210,73%,58%) | | hsla | Colors in HSLA format (e.g., 210,73%,58%,1) | | ansi | ANSI escape codes for CLI styling |

ANSI Escape Codes

Kolory includes robust support for ANSI escape codes, enabling vibrant and expressive CLI output. It supports 4-bit, 8-bit, and 24-bit color modes, with a chainable syntax for easy styling.

ANSI Features

• Chainable Syntax: Combine styles fluently (e.g., ansi.red.bold.underline('Hello')).
• Fully Typed: TypeScript support for all ANSI styles.
• Comprehensive SGR Codes: Includes all Select Graphic Rendition (SGR) codes.
• Cross-Platform: Works in Node.js, Deno, and ANSI-compatible browser terminals.
• Auto-Reset: Automatically appends \x1b[0m to reset styles after each print.
• Raw Output: Use .apply(text) to retrieve styled strings without printing.

ANSI Usage

import { ansi } from 'kolory';

// Basic styling
ansi.bold('Bold text'); // Bold text
ansi.italic.underline('Stylish!'); // Italicized and underlined text
ansi.red.bgWhite.bold('Alert!'); // Red text on white background, bold
console.log(ansi.green.apply('Green text')); // Returns raw styled string

Supported ANSI Styles

| Category | Styles | | --------------- | ------------------------------------------------------------------------------------------------------------------------------ | | Text Styles | bold, dim, italic, underline, blink, inverse, hidden | | Foreground | black, red, green, yellow, blue, magenta, cyan, white | | Bright FG | gray, brightRed, brightGreen, brightYellow, brightBlue, brightMagenta, brightCyan, brightWhite | | Background | bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite | | Bright BG | bgGray, bgBrightRed, bgBrightGreen, bgBrightYellow, bgBrightBlue, bgBrightMagenta, bgBrightCyan, bgBrightWhite | | Reset | .reset (or automatic after every print) |

ANSI Examples

ansi.inverse('Inverted'); // Inverted text
ansi.brightCyan('Bright Cyan Text'); // Bright cyan text
ansi.bgBrightMagenta.white.bold('Highlight this!'); // White bold text on bright magenta background

How ANSI Works

Kolory’s ANSI support uses dynamic proxy chaining to build escape sequences. Each chained property appends an ANSI code, and the final invocation wraps the text with the appropriate codes:

ansi.red.bold('Hello'); // Outputs: \u001b[31m\u001b[1mHello\u001b[0m

[!NOTE] Use .apply(text) to retrieve the raw styled string for further processing without printing to the console.

Contributing

We welcome contributions to make Kolory even better! To contribute:

1. Add Colors: Add new color entries to kolory.json, following the structure defined in kolory.schema.json.
2. Supported Formats: Ensure each color includes hex, rgb, rgba, hsl, and hsla values.
3. Consistency: Maintain consistent naming and formatting across all entries.
4. Code Quality: Run the formatter (prettier) and linter (eslint) before submitting a pull request.
5. Submit a PR: Open a pull request with a clear description of your changes.

License

Kolory is licensed under the Apache License 2.0.