README.md

🌈 colors

Colorize messages in the terminal and browser

Contents

• What is this?
  • Features
• Install
• Use
• API
  • colors
  • createColors([options])
  • isColorSupported
  • stripAnsi(value[, toString])
• Types
  • ColorConfig
  • ColorConfigs
  • ColorFunction
  • ColorFunctions
  • Color
  • ColorizerOptions
  • Colors
  • ToString
• Contribute

What is this?

This is a small, but useful, library for creating colorful messages in the terminal and browser consoles that support ANSI colors.

Features

• FORCE_COLOR, NO_COLOR, and NODE_DISABLE_COLORS friendly
• automatic color support detection
• no dependencies
• typescript support

Install

This package is ESM only.

In Node.js with yarn:

yarn add @flex-development/colors

See Git - Protocols | Yarn  for details regarding installing from Git.

In Deno with esm.sh:

import { colors } from 'https://esm.sh/@flex-development/colors'

In browsers with esm.sh:

<script type="module">
  import { createColors } from 'https://esm.sh/@flex-development/colors'
</script>

Use

import c from '@flex-development/colors'

console.log(c.red(c.bold('Hello World!')))

API

This package exports the following identifiers:

• colors
• createColors
• isColorSupported
• stripAnsi

The default export is colors.

colors

(Colors) The default colorizer.

createColors([options])

Create a colorizer.

Parameters

• options (ColorizerOptions | boolean, optional) — boolean indicating if color output should be enabled, or an options object to create a custom colorizer
  • default: isColorSupported()

Returns

(Colors) Colorizer object

isColorSupported

Check if color output is supported.

Returns

(boolean) true if color output is supported, false otherwise

stripAnsi(value[, toString])

Remove ANSI escape codes from value.

Parameters

• value (unknown) — the string or value to remove escape codes from
• toString (ToString, optional) — convert value to a string
  • default: String

Returns

(string) Stringified value with ANSI escape codes removed

Types

This package is fully typed with TypeScript.

ColorConfig

List, where the first value is the numeric code for an ANSI escape sequence, and the second is the numeric code for the reset sequence. The last value is an optional replacement for the reset sequence (used in complex cases to nest styles without breaking existing color sequences).

type ColorConfig = [
  open: number,
  close: number,
  replace?: string | null | undefined
]

ColorConfigs

Record, where each key is a Color and each value is the configuration for a color function.

type ColorConfigs = Record<Color, ColorConfig>

ColorFunction

Colorize value (TypeScript interface).

Parameters

• value (unknown) — the thing to colorize

Properties

• close (string) — reset sequence
• open (string) — sequence used to set colors
• replace (string, optional) — reset sequence replacement

Returns

(string) Colorized string value

ColorFunctions

Registry of color functions (TypeScript interface).

Color

Union of color names.

type Color = keyof ColorFunctions

To register custom colors, augment ColorFunctions. They will be added to this union automatically.

declare module '@flex-development/colors' {
 interface ColorFunctions {
   blink: ColorFunction
 }
}

ColorizerOptions

Options for creating a colorizer (TypeScript interface).

Properties

• color (boolean, optional) — color output enabled?
• colors (Partial<ColorConfigs>, optional) — color function config map

Colors

also exported as Colorizer

A colorizer (TypeScript interface).

Colorizers contain Color functions. Each function corresponds to a terminal color or style. The color property is an accessor that can be used to disable or enable color output.

Extends

• ColorFunctions

Properties

• get color(): boolean — color output enabled?
• set color(color: boolean | null | undefined) - enable or disable color output
  👉 note: color output will be disabled if not supported
• supported (boolean) — color output supported? (readonly)

ToString

Convert value to a string (TypeScript type).

Parameters

• value (unknown) — the thing to stringify

Returns

(string) Stringified value

Contribute

See CONTRIBUTING.md.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.