---

---

Why Colorize?

• Supports both ESM and CommonJS
• TypeScript support out of the box
• Supports Deno, Next.JS runtimes and Browser (not only chrome) (currently multi nesting is not supported)
• Standard API compatible with Chalk, switch from Chalk to Colorize without changing your code

1- import chalk from 'chalk';
2+ import chalk, { red } from '@visulima/colorize';
3
4chalk.red.bold('Error!'); // <- Chalk like syntax works fine with Colorize
5red.bold('Error!');       // <- the same result with Colorize
6red.bold`Error!`;         // <- the same result with Colorize

• Default import
  • import colorize from '@visulima/colorize' or const colorize = require('@visulima/colorize')
• Named import
  • import { red } from '@visulima/colorize' or const { red } = require('@visulima/colorize')
• Chained syntax red.bold.underline('text')
• Template literals red`text`
• String styling with tagged template literals, see template-literals
• Nested template strings red`R ${green`G`} R`
• Base ANSI styles dim bold italic underline strikethrough
• Base ANSI 16 colors red`Error!` redBright`Error!` bgRed`Error!` bgRedBright`Error!`
• ANSI 256 colors and TrueColor (RGB, HEX) rgb(224, 17, 95)`Ruby`, hex('#96C')`Amethyst`
• TrueColor (RGB, HEX) rgb(224, 17, 95)`Ruby`, hex('#96C')`Amethyst`
• Fallback to supported color space: TrueColor → 256 colors → 16 colors → no colors
• ANSI codes as open and close property for each style `Hello ${red.open}World${red.close}!`
• Strip ANSI codes method colorize.strip()
• Correct style break at the end of line when used \n in string
• Supports the environment variables NO_COLOR FORCE_COLOR and flags --no-color --color
• Expressive API
• Doesn't extend String.prototype
• Up to x3 faster than chalk, see benchmarks
• Auto detects color support
• Clean and focused
• String Gradient´s

Install

1npm install @visulima/colorize

1yarn add @visulima/colorize

1pnpm add @visulima/colorize

Demo

Usage

1// ESM default import
2import colorize from "@visulima/colorize";
3// ESM named import
4import { red, green, blue } from "@visulima/colorize";

or

1// CommonJS default import
2const colorize = require("@visulima/colorize");
3// CommonJS named import
4const { red, green, blue } = require("@visulima/colorize");

Some examples:

1console.log(colorize.green("Success!"));
2console.log(green("Success!"));
3
4// template string
5console.log(blue`Info!`);
6
7// chained syntax
8console.log(green.bold`Success!`);
9
10// nested syntax
11console.log(red`The ${blue.underline`file.js`} not found!`);

Browser

Note: It has the same API as in Node.js.

The return value of the browser version is an array of strings, not a string, because the browser console use the %c syntax for styling. This is why you need the spread operator ... to log the colorized string.

1// ESM default import
2import colorize from "@visulima/colorize/browser";
3// ESM named import
4import { red, green, blue } from "@visulima/colorize/browser";

Some examples:

1console.log(...colorize.green("Success!"));
2console.log(...green("Success!"));
3
4// template string
5console.log(...blue`Info!`);
6
7// chained syntax
8console.log(...green.bold`Success!`);
9
10// nested syntax
11console.log(...red`The ${blue.underline`file.js`} not found!`);

Workaround/Hack to not use the spread operator ....

Warning: But you will lose the correct file path and line number in the console.

1let consoleOverwritten = false;
2
3// Heck the window.console object to add colorized logging
4if (typeof navigator !== "undefined" && typeof window !== "undefined" && !consoleOverwritten) {
5    ["error", "group", "groupCollapsed", "info", "log", "trace", "warn"].forEach((o) => {
6        const originalMethod = (window.console as any)[o as keyof Console];
7
8        (window.console as any)[o as keyof Console] = (...args: any[]) => {
9            if (Array.isArray(args[0]) && args[0].length >= 2 && args[0][0].includes("%c")) {
10                originalMethod(...args[0]);
11            } else {
12                originalMethod(...args);
13            }
14        };
15    });
16
17    consoleOverwritten = true;
18}

Named import

The @visulima/colorize supports both the default import and named import.

1// default import
2import colorize from "@visulima/colorize";
3
4colorize.red.bold("text");

You can import named colors, styles and functions. All imported colors and styles are chainable.

1// named import
2import { red, hex, italic } from "@visulima/colorize";
3
4red.bold("text");

Default import and named import can be combined.

1// default and named import
2import colorize, { red } from "@visulima/colorize";
3
4const redText = red("text"); // colorized ANSI string
5const text = colorize.strip(redText); // pure string without ANSI codes

Template literals

The @visulima/colorize supports both the function syntax red('error') and template literals red`error`.

The template literals allow you to make a complex template more readable and shorter.
The function syntax can be used to colorize a variable.

1import { red, blue } from "@visulima/colorize";
2
3let message = "error";
4
5red(message);
6blue`text`;
7blue`text ${message} text`;

Tagged Template Literals

The @visulima/colorize supports the tagged template literals.

1import template from "@visulima/colorize/template";
2
3console.log(template`
4CPU: {red ${cpu.totalPercent}%}
5RAM: {green ${(ram.used / ram.total) * 100}%}
6DISK: {rgb(255,131,0) ${(disk.used / disk.total) * 100}%}
7`);
8
9const miles = 18;
10const calculateFeet = (miles) => miles * 5280;
11
12console.log(template`
13    There are {bold 5280 feet} in a mile.
14    In {bold ${miles} miles}, there are {green.bold ${calculateFeet(miles)} feet}.
15`);
16
17console.log(template`
18    There are also {#FF0000 shorthand hex styles} for
19    both the {#ABCDEF foreground}, {#:123456 background},
20    or {#ABCDEF:123456 both}.
21`);

API

Blocks are delimited by an opening curly brace ({), a style, some content, and a closing curly brace (}).

Template styles are chained exactly like normal Colorize styles. The following two statements are equivalent:

1import colorize from "@visulima/colorize";
2import template from "@visulima/colorize/template";
3
4console.log(colorize.bold.rgb(10, 100, 200)("Hello!"));
5console.log(template`{bold.rgb(10,100,200) Hello!}`);

Chained syntax

All colors, styles and functions are chainable. Each color or style can be combined in any order.

1import { blue, bold, italic, hex } from "@visulima/colorize";
2
3blue.bold`text`;
4
5hex("#FF75D1").bgCyan.bold`text`;
6
7bold.bgHex("#FF75D1").cyan`text`;
8
9italic.yellow.bgMagentaBright`text`;

Nested syntax

You can nest functions and template strings within each other. None of the other libraries (chalk, kleur, colorette, colors.js etc.) support nested template strings.

Nested template strings:

1import { red, green } from "@visulima/colorize";
2
3red`red ${green`green`} red`;

Deep nested chained styles:

1import { red, green, cyan, magenta, yellow, italic, underline } from "@visulima/colorize";
2
3console.log(red(`red ${italic(`red italic ${underline(`red italic underline`)}`)} red`));
4
5// deep nested chained styles
6console.log(green(`green ${yellow(`yellow ${magenta(`magenta ${cyan(`cyan ${red.italic.underline`red italic underline`} cyan`)} magenta`)} yellow`)} green`));

Output:

Multiline nested template strings:

1import { red, green, hex, visible, inverse } from "@visulima/colorize";
2
3// defined a TrueColor as the constant
4const orange = hex("#FFAB40");
5
6// normal colors
7console.log(visible`
8CPU: ${red`${cpu.totalPercent}%`}
9RAM: ${green`${(ram.used / ram.total) * 100}%`}
10DISK: ${orange`${(disk.used / disk.total) * 100}%`}
11`);
12
13// inversed colors
14console.log(inverse`
15CPU: ${red`${cpu.totalPercent}%`}
16RAM: ${green`${(ram.used / ram.total) * 100}%`}
17DISK: ${orange`${(disk.used / disk.total) * 100}%`}
18`);

Output:

Base ANSI 16 colors and styles

Colors and styles have standard names used by many popular libraries, such as chalk, colorette, kleur.

Foreground colors	Background colors	Styles
black	bgBlack	dim
red	bgRed	bold
green	bgGreen	italic
yellow	bgYellow	underline
blue	bgBlue	strikethrough (alias strike)
magenta	bgMagenta	doubleUnderline (not included, because not widely supported)
cyan	bgCyan	overline (not included, because not widely supported)
white	bgWhite	frame (not included, because not widely supported)
gray (alias grey)	bgGray (alias bgGrey)	encircle (not included, because not widely supported)
blackBright	bgBlackBright	inverse
redBright	bgRedBright	visible
greenBright	bgGreenBright	hidden
yellowBright	bgYellowBright	reset
blueBright	bgBlueBright
magentaBright	bgMagentaBright
cyanBright	bgCyanBright
whiteBright	bgWhiteBright

ANSI 256 colors

The pre-defined set of 256 colors.

Browser

Code range	Description
0 - 7	standard colors
8 - 15	bright colors
16 - 231	6 × 6 × 6 cube (216 colors)
232 - 255	grayscale from black to white in 24 steps

Foreground function: ansi256(code) has short alias fg(code)
Background function: bgAnsi256(code) has short alias bg(code)

The ansi256() and bgAnsi256() methods are implemented for compatibility with the chalk API.

See ANSI color codes.

Fallback

If a terminal supports only 16 colors then ANSI 256 colors will be interpolated into base 16 colors.

Usage Example

1import { bold, ansi256, fg, bgAnsi256, bg } from "@visulima/colorize";
2
3// foreground color
4ansi256(96)`Bright Cyan`;
5fg(96)`Bright Cyan`; // alias for ansi256
6
7// background color
8bgAnsi256(105)`Bright Magenta`;
9bg(105)`Bright Magenta`; // alias for bgAnsi256
10
11// function is chainable
12ansi256(96).bold`bold Bright Cyan`;
13
14// function is avaliable in each style
15bold.ansi256(96).underline`bold underline Bright Cyan`;
16
17// you can combine the functions and styles in any order
18bgAnsi256(105).ansi256(96)`cyan text on magenta background`;
19bg(105).fg(96)`cyan text on magenta background`;

1import { bold, ansi256, fg, bgAnsi256, bg } from "@visulima/colorize";
2
3// foreground color
4ansi256(96)`Bright Cyan`;
5fg(96)`Bright Cyan`;
6
7// background color
8bgAnsi256(105)`Bright Magenta`;
9bg(105)`Bright Magenta`;
10
11// function is chainable
12ansi256(96).bold`bold Bright Cyan`;
13
14// function is available in each style
15bold.ansi256(96).underline`bold underline Bright Cyan`;
16
17// you can combine the functions and styles in any order
18bgAnsi256(105).ansi256(96)`cyan text on magenta background`;
19bg(105).fg(96)`cyan text on magenta background`;

Truecolor (16 million colors)

You can use the hex or rgb format.

Foreground function: hex() rgb()
Background function: bgHex() bgRgb()

1import { bold, hex, rgb, bgHex, bgRgb } from "@visulima/colorize";
2
3// foreground color
4hex("#E0115F").bold`bold Ruby`;
5hex("#96C")`Amethyst`;
6rgb(224, 17, 95).italic`italic Ruby`;
7
8// background color
9bgHex("#E0115F")`Ruby`;
10bgHex("#96C")`Amethyst`;
11bgRgb(224, 17, 95)`Ruby`;
12
13// you can combine the functions and styles in any order
14bold.hex("#E0115F").bgHex("#96C")`ruby bold text on amethyst background`;

Fallback

If a terminal does not support ANSI colors, the library will automatically fall back to the next supported color space.

TrueColor —> 256 colors —> 16 colors —> no colors (black & white)

If you use the hex(), rgb() or ansis256() functions in a terminal not supported TrueColor or 256 colors, then colors will be interpolated.

Use ANSI codes

You can use the ANSI escape codes with open and close properties for each style.

1import { green, bold } from "@visulima/colorize";
2
3// each style has `open` and `close` properties
4console.log(`Hello ${green.open}ANSI${green.close} World!`);
5
6// you can define own style which will have the `open` and `close` properties
7const myStyle = bold.italic.black.bgHex("#E0115F");
8
9console.log(`Hello ${myStyle.open}ANSI${myStyle.close} World!`);

Strip ANSI codes

The Colorize class contains the method strip() to remove all ANSI codes from string.

1import colorize from "@visulima/colorize";
2// or named import
3import { strip } from "@visulima/colorize";
4
5const ansiString = colorize.blue`Hello World!`;
6const string = colorize.strip(ansiString);

The variable string will contain the pure string without ANSI codes.

New lines

Supports correct style break at the end of line.

1import { bgGreen } from "@visulima/colorize";
2
3console.log(bgGreen`\nColorize\nNew Line\nNext New Line\n`);

Environment variables and CLI arguments

Please check @visulima/is-ansi-color-supported for more information.

Browser support

Since Chrome 69 (every chrome based browser), ANSI escape codes are natively supported in the developer console.

For other browsers (like firefox) we use the console style syntax command %c.

Windows

If you're on Windows, do yourself a favor and use Windows Terminal instead of cmd.exe.

Comparison of most popular libraries

Library **__** - name - named import	Code size	Naming colors	ANSI 256 colors	True- color	Chained syntax	Nested template strings	New Line	Supports CLI params ENV vars	Fallbacks
@visulima/colorize ✅ named import		standard 16 colors	✅	✅	✅	✅	✅	NO_COLOR FORCE_COLOR --no-color --color	256 color 16 colors no color
ansi-colors ❌ named import		standard 16 colors	❌	❌	✅	❌	✅	only FORCE_COLOR	❌
ansis ✅ named import		standard 16 colors	✅	✅	✅	✅	✅	NO_COLOR FORCE_COLOR --no-color --color	256 color 16 colors no color
chalk ❌ named import		standard 16 colors	✅	✅	✅	❌	✅	NO_COLOR FORCE_COLOR --no-color --color	256 color 16 colors no color
cli-color ❌ named import		standard 16 colors	✅	❌	✅	❌	❌	only NO_COLOR	16 colors no color
colorette ✅ named import		standard 16 colors	❌	❌	❌	❌	❌	NO_COLOR FORCE_COLOR --no-color --color	no color
colors-cli ❌ named import		non-standard 16 colors	✅	❌	✅	❌	✅	only --no-color --color	no color
colors.js ❌ named import		non-standard 16 colors	❌	❌	✅	❌	✅	only FORCE_COLOR --no-color --color	no color
kleur ✅ named import		standard 8 colors	❌	❌	✅	❌	❌	only NO_COLOR FORCE_COLOR	no color
picocolors ❌ named import		standard 8 colors	❌	❌	❌	❌	❌	NO_COLOR FORCE_COLOR --no-color --color	no color

Note

Code size
The size of distributed code that will be loaded via require or import into your app. It's not a package size.

Named import
import { red, green, blue } from 'lib';
or
const { red, green, blue } = require('lib');

Naming colors

• standard: colors have standard names, e.g.: red, redBright, bgRed, bgRedBright
• non-standard: colors have lib-specific names, e.g.: brightRed, bgBrightRed, red_b, red_btt

ANSI 256 colors

The method names:

• @visulima/colorize: ansi256(n) bgAnsi256(n) fg(n) bg(n)
• ansis: ansi256(n) bgAnsi256(n) fg(n) bg(n)
• chalk: ansi256(n) bgAnsi256(n)
• cli-color: xterm(n)
• colors-cli: x<n>

Truecolor

The method names:

• @visulima/colorize: hex() rgb()
• ansis: hex() rgb()
• chalk: hex() rgb()

Chained syntax
lib.red.bold('text')

Nested template strings
lib.red`text ${lib.cyan`nested`} text`

New line
Correct break styles at end-of-line.

lib.bgGreen(`First Line
Next Line`);

Gradient

The @visulima/colorize/gradient supports the string gradient´s, single and multi line.

1import { gradient } from "@visulima/colorize/gradient";
2
3console.log(gradient("red", "green", "blue")("Hello World!"));

Multi line gradient

In some cases, you may want to apply the same horizontal gradient on each line of a long text (or a piece of ASCII art).

You can use the multilineGradient method of a gradient to ensure that the colors are vertically aligned.

1import { multilineGradient, gradient } from "@visulima/colorize/gradient";
2
3console.log(multilineGradient(["orange", "yellow"])(["     __", "   <(o )___", "    ( ._> /", "     `---'"].join("\n")));
4console.log(gradient(["blue", "cyan", "blue"])("----------------"));

Benchmark

See benchmark

Reference

• The opaque named colors
• ANSI escape code

The ANSI Escape sequences control code screen.

1echo -e "\033[31;41;4m something here 33[0m"

\033 As the escape character, inform the terminal to switch to the escape mode. [ The beginning of the CSI. m Make the action to be performed. ; ASCII code separator.

Supported Node.js Versions

Libraries in this ecosystem make the best effort to track Node.js’ release schedule. Here’s a post on why we think this is important.

Contributing

If you would like to help take a look at the list of issues and check our Contributing guild.

Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Credits

• WebDiscus
• Daniel Bannert
• All Contributors

About

Related Projects

• ansis - The Node.js library for formatting text in terminal with ANSI colors & styles
• ansi-colors - Easily add ANSI colors to your text and symbols in the terminal.
• chalk - Terminal string styling done right
• cli-color - Colors and formatting for the console
• colorette - Easily set your terminal text color & styles
• colors-cli - Terminal string styling done right.
• colors.js - get colors in your node.js console
• kleur - The fastest Node.js library for formatting terminal text with ANSI colors~!
• picocolors - Tiny yet powerful colors for terminal

Template:

• chalk-template - Terminal string styling with tagged template literals

Gradient:

• tinygradient - Easily generate color gradients with an unlimited number of color stops and steps.
• gradient-string - Beautiful color gradients in terminal output

License

The visulima colorize is open-sourced software licensed under the MIT