https://github.com/teneplaysofficial/kolory
Paint your projects with vibrant Kolory
https://github.com/teneplaysofficial/kolory
color-conversion color-utils colors frontend-tools hex-rgb-hsl javascript library npm-package palette-generator web-design
Last synced: 6 months ago
JSON representation
Paint your projects with vibrant Kolory
- Host: GitHub
- URL: https://github.com/teneplaysofficial/kolory
- Owner: teneplaysofficial
- License: apache-2.0
- Created: 2025-07-29T12:55:29.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-08-05T09:50:05.000Z (11 months ago)
- Last Synced: 2025-08-05T11:37:21.533Z (11 months ago)
- Topics: color-conversion, color-utils, colors, frontend-tools, hex-rgb-hsl, javascript, library, npm-package, palette-generator, web-design
- Language: TypeScript
- Homepage:
- Size: 62.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/funding.yml
- License: LICENSE
Awesome Lists containing this project
README
> [!WARNING]
> This repository has been **moved**. Please use the new location instead: 👉 [https://github.com/teneplaysofficial/omnijs](https://github.com/teneplaysofficial/omnijs)
# Kolory
_Paint your projects with vibrant Kolory_
[](https://github.com/teneplaysofficial/kolory/actions/workflows/release.yml)
[](./LICENSE)
[](https://github.com/teneplaysofficial/kolory)
[](https://github.com/teneplaysofficial/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
```bash
# 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:
```html
import kolory from 'https://esm.sh/kolory';
```
## Usage
Kolory provides a straightforward API to access and manipulate colors in various formats. Below are examples for different environments.
### ESM (Modern JavaScript)
```js
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
```js
const { hex, rgb } = require('kolory');
console.log(hex.sunset_orange);
console.log(rgb.sunset_orange);
```
### Browser (IIFE via CDN)
```html
console.log(kolory.hex.blue_metal);
```
## 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:
```json
{
"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
```js
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
```js
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:
```js
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](./kolory.json), following the structure defined in [kolory.schema.json](./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](./LICENSE).