Github url

chalk

by chalk

chalk /chalk

πŸ– Terminal string styling done right

14.9K Stars 578 Forks Last release: 2 months ago (v4.1.0) MIT License 298 Commits 30 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Chalk

Terminal string styling done right

Build Status Coverage Status npm dependents Downloads XO code style TypeScript-ready run on repl.it

Highlights

Install

$ npm install chalk

Usage

const chalk = require('chalk'); console.log(chalk.blue('Hello world!'));

Chalk comes with an easy to use composable API where you just chain and nest the styles you want.

const chalk = require('chalk'); const log = console.log; // Combine styled and normal strings log(chalk.blue('Hello') + ' World' + chalk.red('!')); // Compose multiple styles using the chainable API log(chalk.blue.bgRed.bold('Hello world!')); // Pass in multiple arguments log(chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz')); // Nest styles log(chalk.red('Hello', chalk.underline.bgBlue('world') + '!')); // Nest styles of the same type even (color, underline, background) log(chalk.green( 'I am a green line ' + chalk.blue.underline.bold('with a blue substring') + ' that becomes green again!' )); // ES2015 template literal log(` CPU: ${chalk.red('90%')} RAM: ${chalk.green('40%')} DISK: ${chalk.yellow('70%')} `); // ES2015 tagged template literal log(chalk` CPU: {red ${cpu.totalPercent}%} RAM: {green ${ram.used / ram.total * 100}%} DISK: {rgb(255,131,0) ${disk.used / disk.total * 100}%} `); // Use RGB colors in terminal emulators that support it. log(chalk.keyword('orange')('Yay for orange colored text!')); log(chalk.rgb(123, 45, 67).underline('Underlined reddish color')); log(chalk.hex('#DEADED').bold('Bold gray!'));

Easily define your own themes:

const chalk = require('chalk'); const error = chalk.bold.red; const warning = chalk.keyword('orange'); console.log(error('Error!')); console.log(warning('Warning!'));

Take advantage of console.log string substitution:

const name = 'Sindre'; console.log(chalk.green('Hello %s'), name); //=\> 'Hello Sindre'

API

chalk.

<style>[.<style>...](string, [string...])</pre></h3>

<p>Example: <pre class="">chalk.red.bold.underline('Hello', 'world');</pre></p>

<p>Chain <a href="#styles">styles</a> and call the last one as a method with a string argument. Order doesn&#39;t matter, and later styles take precedent in case of a conflict. This simply means that <pre class="">chalk.red.yellow.green</pre> is equivalent to <pre class="">chalk.green</pre>.</p>

<p>Multiple arguments will be separated by space.</p>

<h3>chalk.level</h3>

<p>Specifies the level of color support.</p>

<p>Color support is automatically detected, but you can override it by setting the <pre class="">level</pre> property. You should however only do this in your own code as it applies globally to all Chalk consumers.</p>

<p>If you need to change this in a reusable module, create a new instance:</p>
<pre class="js">const ctx = new chalk.Instance({level: 0});
</pre>
<p>| Level | Description |
| :---: | :--- |
| <pre class="">0</pre> | All colors disabled |
| <pre class="">1</pre> | Basic color support (16 colors) |
| <pre class="">2</pre> | 256 color support |
| <pre class="">3</pre> | Truecolor support (16 million colors) |</p>

<h3>chalk.supportsColor</h3>

<p>Detect whether the terminal <a href="https://github.com/chalk/supports-color">supports color</a>. Used internally and handled for you, but exposed for convenience.</p>

<p>Can be overridden by the user with the flags <pre class="">--color</pre> and <pre class="">--no-color</pre>. For situations where using <pre class="">--color</pre> is not possible, use the environment variable <pre class="">FORCE_COLOR=1</pre> (level 1), <pre class="">FORCE_COLOR=2</pre> (level 2), or <pre class="">FORCE_COLOR=3</pre> (level 3) to forcefully enable color, or <pre class="">FORCE_COLOR=0</pre> to forcefully disable. The use of <pre class="">FORCE_COLOR</pre> overrides all other color support checks.</p>

<p>Explicit 256/Truecolor mode can be enabled using the <pre class="">--color=256</pre> and <pre class="">--color=16m</pre> flags, respectively.</p>

<h3>chalk.stderr and chalk.stderr.supportsColor</h3>

<p><pre class="">chalk.stderr</pre> contains a separate instance configured with color support detected for <pre class="">stderr</pre> stream instead of <pre class="">stdout</pre>. Override rules from <pre class="">chalk.supportsColor</pre> apply to this too. <pre class="">chalk.stderr.supportsColor</pre> is exposed for convenience.</p>

<h2>Styles</h2>

<h3>Modifiers</h3>

<ul>
<li><pre class="">reset</pre> - Resets the current color chain.</li>
<li><pre class="">bold</pre> - Make text bold.</li>
<li><pre class="">dim</pre> - Emitting only a small amount of light.</li>
<li><pre class="">italic</pre> - Make text italic. <em>(Not widely supported)</em></li>
<li><pre class="">underline</pre> - Make text underline. <em>(Not widely supported)</em></li>
<li><pre class="">inverse</pre>- Inverse background and foreground colors.</li>
<li><pre class="">hidden</pre> - Prints the text, but makes it invisible.</li>
<li><pre class="">strikethrough</pre> - Puts a horizontal line through the center of the text. <em>(Not widely supported)</em></li>
<li><pre class="">visible</pre>- Prints the text only when Chalk has a color level &gt; 0. Can be useful for things that are purely cosmetic.</li>
</ul>

<h3>Colors</h3>

<ul>
<li><pre class="">black</pre></li>
<li><pre class="">red</pre></li>
<li><pre class="">green</pre></li>
<li><pre class="">yellow</pre></li>
<li><pre class="">blue</pre></li>
<li><pre class="">magenta</pre></li>
<li><pre class="">cyan</pre></li>
<li><pre class="">white</pre></li>
<li><pre class="">blackBright</pre> (alias: <pre class="">gray</pre>, <pre class="">grey</pre>)</li>
<li><pre class="">redBright</pre></li>
<li><pre class="">greenBright</pre></li>
<li><pre class="">yellowBright</pre></li>
<li><pre class="">blueBright</pre></li>
<li><pre class="">magentaBright</pre></li>
<li><pre class="">cyanBright</pre></li>
<li><pre class="">whiteBright</pre></li>
</ul>

<h3>Background colors</h3>

<ul>
<li><pre class="">bgBlack</pre></li>
<li><pre class="">bgRed</pre></li>
<li><pre class="">bgGreen</pre></li>
<li><pre class="">bgYellow</pre></li>
<li><pre class="">bgBlue</pre></li>
<li><pre class="">bgMagenta</pre></li>
<li><pre class="">bgCyan</pre></li>
<li><pre class="">bgWhite</pre></li>
<li><pre class="">bgBlackBright</pre> (alias: <pre class="">bgGray</pre>, <pre class="">bgGrey</pre>)</li>
<li><pre class="">bgRedBright</pre></li>
<li><pre class="">bgGreenBright</pre></li>
<li><pre class="">bgYellowBright</pre></li>
<li><pre class="">bgBlueBright</pre></li>
<li><pre class="">bgMagentaBright</pre></li>
<li><pre class="">bgCyanBright</pre></li>
<li><pre class="">bgWhiteBright</pre></li>
</ul>

<h2>Tagged template literal</h2>

<p>Chalk can be used as a <a href="https://exploringjs.com/es6/ch_template-literals.html#_tagged-template-literals">tagged template literal</a>.</p>
<pre class="js">const chalk = require('chalk');

const miles = 18;
const calculateFeet = miles => miles * 5280;

console.log(chalk`
    There are {bold 5280 feet} in a mile.
    In {bold ${miles} miles}, there are {green.bold ${calculateFeet(miles)} feet}.
`);
</pre>
<p>Blocks are delimited by an opening curly brace (<pre class="">{</pre>), a style, some content, and a closing curly brace (<pre class="">}</pre>).</p>

<p>Template styles are chained exactly like normal Chalk styles. The following three statements are equivalent:</p>
<pre class="js">console.log(chalk.bold.rgb(10, 100, 200)('Hello!'));
console.log(chalk.bold.rgb(10, 100, 200)`Hello!`);
console.log(chalk`{bold.rgb(10,100,200) Hello!}`);
</pre>
<p>Note that function styles (<pre class="">rgb()</pre>, <pre class="">hsl()</pre>, <pre class="">keyword()</pre>, etc.) may not contain spaces between parameters.</p>

<p>All interpolated values (<pre class="">chalk`${foo}`</pre>) are converted to strings via the <pre class="">.toString()</pre> method. All curly braces (<pre class="">{</pre> and <pre class="">}</pre>) in interpolated value strings are escaped.</p>

<h2>256 and Truecolor color support</h2>

<p>Chalk supports 256 colors and <a href="https://gist.github.com/XVilka/8346728">Truecolor</a> (16 million colors) on supported terminal apps.</p>

<p>Colors are downsampled from 16 million RGB values to an ANSI color format that is supported by the terminal emulator (or by specifying <pre class="">{level: n}</pre> as a Chalk option). For example, Chalk configured to run at level 1 (basic color support) will downsample an RGB value of #FF0000 (red) to 31 (ANSI escape for red).</p>

<p>Examples:</p>

<ul>
<li><pre class="">chalk.hex('#DEADED').underline('Hello, world!')</pre></li>
<li><pre class="">chalk.keyword('orange')('Some orange text')</pre></li>
<li><pre class="">chalk.rgb(15, 100, 204).inverse('Hello!')</pre></li>
</ul>

<p>Background versions of these models are prefixed with <pre class="">bg</pre> and the first level of the module capitalized (e.g. <pre class="">keyword</pre> for foreground colors and <pre class="">bgKeyword</pre> for background colors).</p>

<ul>
<li><pre class="">chalk.bgHex('#DEADED').underline('Hello, world!')</pre></li>
<li><pre class="">chalk.bgKeyword('orange')('Some orange text')</pre></li>
<li><pre class="">chalk.bgRgb(15, 100, 204).inverse('Hello!')</pre></li>
</ul>

<p>The following color models can be used:</p>

<ul>
<li><a href="https://en.wikipedia.org/wiki/RGB_color_model"><pre class="">rgb</pre></a> - Example: <pre class="">chalk.rgb(255, 136, 0).bold('Orange!')</pre></li>
<li><a href="https://en.wikipedia.org/wiki/Web_colors#Hex_triplet"><pre class="">hex</pre></a> - Example: <pre class="">chalk.hex('#FF8800').bold('Orange!')</pre></li>
<li><a href="https://www.w3.org/wiki/CSS/Properties/color/keywords"><pre class="">keyword</pre></a> (CSS keywords) - Example: <pre class="">chalk.keyword('orange').bold('Orange!')</pre></li>
<li><a href="https://en.wikipedia.org/wiki/HSL_and_HSV"><pre class="">hsl</pre></a> - Example: <pre class="">chalk.hsl(32, 100, 50).bold('Orange!')</pre></li>
<li><a href="https://en.wikipedia.org/wiki/HSL_and_HSV"><pre class="">hsv</pre></a> - Example: <pre class="">chalk.hsv(32, 100, 100).bold('Orange!')</pre></li>
<li><a href="https://en.wikipedia.org/wiki/HWB_color_model"><pre class="">hwb</pre></a> - Example: <pre class="">chalk.hwb(32, 0, 50).bold('Orange!')</pre></li>
<li><a href="https://en.wikipedia.org/wiki/ANSI_escape_code#3/4_bit"><pre class="">ansi</pre></a> - Example: <pre class="">chalk.ansi(31).bgAnsi(93)('red on yellowBright')</pre></li>
<li><a href="https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit"><pre class="">ansi256</pre></a> - Example: <pre class="">chalk.bgAnsi256(194)('Honeydew, more or less')</pre></li>
</ul>

<h2>Windows</h2>

<p>If you&#39;re on Windows, do yourself a favor and use <a href="https://github.com/microsoft/terminal">Windows Terminal</a> instead of <pre class="">cmd.exe</pre>.</p>

<h2>Origin story</h2>

<p><a href="https://github.com/Marak/colors.js">colors.js</a> used to be the most popular string styling module, but it has serious deficiencies like extending <pre class="">String.prototype</pre> which causes all kinds of <a href="https://github.com/yeoman/yo/issues/68">problems</a> and the package is unmaintained. Although there are other packages, they either do too much or not enough. Chalk is a clean and focused alternative.</p>

<h2>chalk for enterprise</h2>

<p>Available as part of the Tidelift Subscription.</p>

<p>The maintainers of chalk and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. <a href="https://tidelift.com/subscription/pkg/npm-chalk?utm_source=npm-chalk&utm_medium=referral&utm_campaign=enterprise&utm_term=repo">Learn more.</a></p>

<h2>Related</h2>

<ul>
<li><a href="https://github.com/chalk/chalk-cli">chalk-cli</a> - CLI for this module</li>
<li><a href="https://github.com/chalk/ansi-styles">ansi-styles</a> - ANSI escape codes for styling strings in the terminal</li>
<li><a href="https://github.com/chalk/supports-color">supports-color</a> - Detect whether a terminal supports color</li>
<li><a href="https://github.com/chalk/strip-ansi">strip-ansi</a> - Strip ANSI escape codes</li>
<li><a href="https://github.com/chalk/strip-ansi-stream">strip-ansi-stream</a> - Strip ANSI escape codes from a stream</li>
<li><a href="https://github.com/chalk/has-ansi">has-ansi</a> - Check if a string has ANSI escape codes</li>
<li><a href="https://github.com/chalk/ansi-regex">ansi-regex</a> - Regular expression for matching ANSI escape codes</li>
<li><a href="https://github.com/chalk/wrap-ansi">wrap-ansi</a> - Wordwrap a string with ANSI escape codes</li>
<li><a href="https://github.com/chalk/slice-ansi">slice-ansi</a> - Slice a string with ANSI escape codes</li>
<li><a href="https://github.com/qix-/color-convert">color-convert</a> - Converts colors between different models</li>
<li><a href="https://github.com/bokub/chalk-animation">chalk-animation</a> - Animate strings in the terminal</li>
<li><a href="https://github.com/bokub/gradient-string">gradient-string</a> - Apply color gradients to strings</li>
<li><a href="https://github.com/LitoMore/chalk-pipe">chalk-pipe</a> - Create chalk style schemes with simpler style strings</li>
<li><a href="https://github.com/sindresorhus/terminal-link">terminal-link</a> - Create clickable links in the terminal</li>
</ul>

<h2>Maintainers</h2>

<ul>
<li><a href="https://github.com/sindresorhus">Sindre Sorhus</a></li>
<li><a href="https://github.com/qix-">Josh Junon</a></li>
</ul>
</style>

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.