🌈 colors

Style messages in the terminal and browser

Contents

• What is this?
  • Features
• Install
• Use
• API
  • colors
  • createColors([options])
  • isColorSupported()
• Types
  • ColorConfig
  • ColorConfigs
  • ColorFunction
  • ColorFunctions
  • Color
  • ColorizerOptions
  • Colors
• 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>

With bun:

bun add @flex-development/colors

See bun add for more details.

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

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

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) — the reset sequence
• open (string) — the sequence used to set styles
• replace (string, optional) — the 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) — whether color output should be enabled
• colors (Partial<ColorConfigs>, optional) — record, where each key is a the name of a color or style and each value is the configuration for that color or style

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
• styles (ColorConfigs) — record, where each key is the name of a color or style and each value is the configuration for a color function (readonly)
• supported (boolean) — whether color output is supported (readonly)

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.