JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 38
  • Score
    100M100P100Q49383F
  • License GPL-3.0

Apply ANSI colors to strings!

Package Exports

  • colorix
  • colorix/ansi.d.mts
  • colorix/ansi.mjs
  • colorix/color-sequence.d.mts
  • colorix/color-sequence.mjs
  • colorix/colors.d.mts
  • colorix/colors.mjs
  • colorix/index.d.mts
  • colorix/index.mjs
  • colorix/map-colors-to-codes.d.mts
  • colorix/map-colors-to-codes.mjs
  • colorix/modules
  • colorix/modules/colorix-error.d.mts
  • colorix/modules/colorix-error.mjs
  • colorix/modules/colorix-safe.d.mts
  • colorix/modules/colorix-safe.mjs
  • colorix/modules/colorix.d.mts
  • colorix/modules/colorix.mjs
  • colorix/modules/index.d.mts
  • colorix/modules/index.mjs
  • colorix/modules/ink-presets.d.mts
  • colorix/modules/ink-presets.mjs
  • colorix/modules/pretty-error.d.mts
  • colorix/modules/pretty-error.mjs
  • colorix/modules/safe.d.mts
  • colorix/modules/safe.mjs
  • colorix/modules/supports-color.d.mts
  • colorix/modules/supports-color.mjs
  • colorix/package.json
  • colorix/reset.d.mts
  • colorix/reset.mjs
  • colorix/types
  • colorix/types/ansi.d.mts
  • colorix/types/ansi.mjs
  • colorix/types/apply-style.d.mts
  • colorix/types/apply-style.mjs
  • colorix/types/color-sequence.d.mts
  • colorix/types/color-sequence.mjs
  • colorix/types/colorix-error.d.mts
  • colorix/types/colorix-error.mjs
  • colorix/types/colorix.d.mts
  • colorix/types/colorix.mjs
  • colorix/types/colors.d.mts
  • colorix/types/colors.mjs
  • colorix/types/index.d.mts
  • colorix/types/index.mjs
  • colorix/types/map-colors-to-codes.d.mts
  • colorix/types/map-colors-to-codes.mjs
  • colorix/types/pretty-error.d.mts
  • colorix/types/pretty-error.mjs
  • colorix/utils
  • colorix/utils/index.d.mts
  • colorix/utils/index.mjs
  • colorix/utils/is-string.d.mts
  • colorix/utils/is-string.mjs
  • colorix/utils/join.d.mts
  • colorix/utils/join.mjs

Readme

Colorix

Colorix helps you recognize and track ansi escape sequences in your code, and provides a simple way to define and layer color presets.

import cx from 'colorix'

const goblinInk = cx('bgGreen', 'black', 'bold')
console.log(goblinInk('hello goblin', '!'))

goblin-example

With TypeScript, you'll see how the color sequences are applied to your strings.

declare const goblinMessage: Colorix<['bgGreen', 'black', 'bold'], ['hello goblin', '!']>
// => `\u001B[42;30;1mhello goblin!\u001B[0m`

This is useful with primitive strings as well.

declare const goblinMessage: Colorix<['bgGreen', 'black', 'bold'], [string, ...string[]]>
// => `\u001B[42;30;1m${string}\u001B[0m`

How it works

// create a theme by passing colors to the first function.
declare const cx: <Colors extends Color[]>(
  ...colors: Colors
) => // then pass stringifiable values to the second function to colorize them.
<Strings extends Stringifiable[]>(
  ...strings: Strings
) => // the returned value is an ansified string.
Colorix<Colors, Strings>

Installation

Add colorix to your project using your favorite package manager.

NPM

npm install colorix

PNPM

pnpm add colorix

Yarn

yarn add colorix

How to support terminals without color

safe, colorixSafe, cxs

You can use safe to check if the terminal supports color before applying a preset.

import cx, { safe } from 'colorix'
const errorInk = cx('bold', 'red')

console.log(errorInk('That tasted purple...'))
// "\u001B[mThat tasted purple...\u001B[0m"

console.log(safe(errorInk)('That tasted purple...'))
// "That tasted purple..." | "\u001B[mThat tasted purple...\u001B[0m"

Alternatively, use colorixSafe / cxs for an Ink preset that only applies colors if the terminal supports it.

import { cxs, colorixSafe } from 'colorix'

const safeErrorInk = cxs('bold', 'red') // or colorixSafe('bold', 'red')
console.log(safeErrorInk('That tasted purple...'))

Bonus Features

ColorixError

ColorixError can be used to extend the Error class. This is useful for throwing consistent, legible, contextual errors.

import { ColorixError } from 'colorix'

const FileNotFoundError = ColorixError('FileNotFoundError', 'Critical file is missing!')

throw new FileNotFoundError(
  'File at',
  (style) => style.path('file.txt'),
  'does not exist. Check the documentation for more information',
  (style) => style.link('https://github.com/Cuppachino/colorix')
)

PrettyError

For an "out-of-the-box" solution, use PrettyError. It provides the same naming and fallback message behavior as Colorix without an api for customizing the rest of the error.

import { PrettyError } from 'colorix'

const IOError = PrettyError('IOError', 'An unknown IO error occurred.')

try {
  throw new IOError()
} catch (err) {
  console.log(err)
}

try {
  throw new IOError('Illegal write operation.', 'more info...')
} catch (err) {
  console.log(err)
}

Exports

default, colorix, cx

Colorix Description
default / cx / colorix Create presets for colorizing Stringifiable values.
cxs / colorixSafe Create presets for colorizing when the terminal supports it Stringifiable.
safe Call a colorix preset safely safe(cx( ...colors )).
ColorixError Create child Error classes with colorized messages.

Constants

Name Description
CSI control sequence introducer ("\x1b[")
SGRT select graphic rendition terminator ("m")
FOREGROUND readonly foreground lookup object
BACKGROUND readonly background lookup object
MODIFIER readonly modifier lookup object
COLORS readonly color lookup object (foreground, background, and modifiers)
hasBasicColors boolean indicating if the terminal supports basic colors
has256Colors boolean indicating if the terminal supports 256 colors
has16mColors boolean indicating if the terminal supports 16 million colors
supportsColor boolean indicating if the terminal supports any color

Types

Generic Description
Colorix utility for creating literals wrapped in ANSI sequences
ColorSequence utility for creating literal ANSI sequences
Alias Description
ResetSequence literal reset sequence that is always appended to the end of a color sequence
ColorTable readonly record of color aliases and color codes
Color a foreground, background, or modifier color (keyof ColorTable)
ColorCode an SGR color code
Foreground a foreground color
Background a background color
Modifier a modifier color

Color Tables

Foreground Code Foreground Bright Code
"black" 30 "gray" 90
"red" 31 "redBright" 91
"green" 32 "greenBright" 92
"yellow" 33 "yellowBright" 93
"blue" 34 "blueBright" 94
"magenta" 35 "magentaBright" 95
"cyan" 36 "cyanBright" 96
"white" 37 "whiteBright" 97
Background Code Background Bright Code
"bgBlack" 40 "bgGray" 100
"bgRed" 41 "bgRedBright" 101
"bgGreen" 42 "bgGreenBright" 102
"bgYellow" 43 "bgYellowBright" 103
"bgBlue" 44 "bgBlueBright" 104
"bgMagenta" 45 "bgMagentaBright" 105
"bgCyan" 46 "bgCyanBright" 106
"bgWhite" 47 "bgWhiteBright" 107
Modifier Code
"reset" 0
"bold" 1
"dim" 2
"italic" 3
"underline" 4
"inverse" 7
"hidden" 8
"strikethrough" 9