or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

chainable-api.mdcolor-detection.mdcolors-api.mdindex.md
tile.json

tessl/npm-kleur

The fastest Node.js library for formatting terminal text with ANSI colors

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/kleur@4.1.x

To install, run

npx @tessl/cli install tessl/npm-kleur@4.1.0

index.mddocs/

Kleur

Kleur is the fastest Node.js library for formatting terminal text with ANSI colors. It provides a zero-dependency, highly performant solution for adding colors, backgrounds, and text modifiers to console output, with conditional color support and both chainable and tree-shakeable APIs.

Package Information

  • Package Name: kleur
  • Package Type: npm
  • Language: JavaScript (with TypeScript definitions)
  • Installation: npm install kleur

Core Imports

Main API (chainable methods):

import kleur from "kleur";

For CommonJS:

const kleur = require("kleur");

Tree-shakeable colors API:

import { red, bold, bgBlue } from "kleur/colors";

For CommonJS:

const { red, bold, bgBlue } = require("kleur/colors");

Basic Usage

import kleur from "kleur";

// Simple color application
console.log(kleur.red("Error: Something went wrong"));
console.log(kleur.green("Success: Operation completed"));

// Chained styling
console.log(kleur.bold().red().underline("Important message"));

// Nested colors
console.log(kleur.yellow(`Warning: ${kleur.red().bold("critical")} issue detected`));

// Complex nested example
console.log(kleur.bold(`${kleur.white().bgRed('[ERROR]')} ${kleur.red().italic('Something happened')}`));

// Tree-shakeable approach
import { red, bold, underline } from "kleur/colors";
console.log(red(bold(underline("Styled text"))));

Architecture

Kleur provides two distinct APIs optimized for different use cases:

  • Main API: Chainable methods on a single kleur object for complex styling combinations
  • Colors API: Individual functions exported from kleur/colors for tree-shaking and functional composition
  • Color Detection: Automatic TTY and environment variable detection with manual override capability
  • ANSI Implementation: Optimized ANSI escape sequence generation with proper nesting support
  • Zero Dependencies: Self-contained implementation for minimal footprint

Capabilities

Chainable Color API

Main kleur API providing chainable methods for complex text styling. Perfect for applications requiring dynamic color combinations and complex formatting.

declare const kleur: Kleur & { enabled: boolean };

interface Kleur {
  // Colors
  black: Color;
  red: Color;
  green: Color;
  yellow: Color;
  blue: Color;
  magenta: Color;
  cyan: Color;
  white: Color;
  gray: Color;
  grey: Color;

  // Backgrounds  
  bgBlack: Color;
  bgRed: Color;
  bgGreen: Color;
  bgYellow: Color;
  bgBlue: Color;
  bgMagenta: Color;
  bgCyan: Color;
  bgWhite: Color;

  // Modifiers
  reset: Color;
  bold: Color;
  dim: Color;
  italic: Color;
  underline: Color;
  inverse: Color;
  hidden: Color;
  strikethrough: Color;
}

interface Color {
  (input: string | number): string;
  (): Kleur;
}

Chainable API

Tree-Shakeable Colors API

Individual color functions for minimal bundle size and functional composition. Ideal for applications where bundle size matters or when using only a few colors.

declare function print(input: string | boolean | number): string;
declare function print(input: undefined | void): undefined;
declare function print(input: null): null;
type Colorize = typeof print;

// Configuration
declare const $: { enabled: boolean };

// All color functions follow the Colorize type
declare const black: Colorize;
declare const red: Colorize;
declare const green: Colorize;
declare const yellow: Colorize;
declare const blue: Colorize;
declare const magenta: Colorize;
declare const cyan: Colorize;
declare const white: Colorize;
declare const gray: Colorize;
declare const grey: Colorize;

// Backgrounds
declare const bgBlack: Colorize;
declare const bgRed: Colorize;
declare const bgGreen: Colorize;
declare const bgYellow: Colorize;
declare const bgBlue: Colorize;
declare const bgMagenta: Colorize;
declare const bgCyan: Colorize;
declare const bgWhite: Colorize;

// Modifiers
declare const reset: Colorize;
declare const bold: Colorize;
declare const dim: Colorize;
declare const italic: Colorize;
declare const underline: Colorize;
declare const inverse: Colorize;
declare const hidden: Colorize;
declare const strikethrough: Colorize;

Tree-Shakeable API

Color Detection and Configuration

Automatic color support detection with manual override capabilities. Handles TTY contexts, environment variables, and cross-platform compatibility.

// Main API
kleur.enabled = false; // Manually disable colors

// Colors API  
import { $ } from "kleur/colors";
$.enabled = false; // Manually disable colors

Color Detection