ansis

Bug Fixes

• color-support: prevent colors in piped or redirected output when COLORTERM is set, #54

• color-support: detect the color level for FORCE_COLOR=true and --color in non-TTY output

Behavior

Colors are enabled only for a TTY, CI, and the PM2 and Next.js runtimes. Output to a pipe or a file has no colors, even when COLORTERM is set. COLORTERM sets only the color level.

FORCE_COLOR=true, FORCE_COLOR= and --color in non-TTY output now detect the level from the environment (COLORTERM, TERM, Windows) instead of always using 16 colors.

Upgrade note

If your tests relied on COLORTERM to get colors, set FORCE_COLOR instead, for example FORCE_COLOR=3 npm test. See Testing.

Bug fixes

1. TERM=dumb now disables colors during auto-detection

Ansis now treats TERM=dumb as no color before applying COLORTERM, CI detection, PM2, Next.js runtime detection, and platform-specific defaults, #49.

Before, COLORTERM=truecolor or other later auto-detection checks could still enable colors even when the environment reported TERM=dumb. This could produce visible ANSI escape codes in environments such as Emacs M-x compile.

COLORTERM remains a color capability hint. FORCE_COLOR keeps the highest priority and can still explicitly enable colors.

* - Depends on additional conditions.

Bug fixes

1. reset no longer appends a closing sequence

Before, reset was treated like any other style with an open and a close code, so it wrapped the value on both sides. That produced extra reset sequences in chained, nested, template literal, and multiline compositions, and the output did not match what a single reset should do.

Before:

ansis.reset('foo');
// "\x1b[0mfoo\x1b[0m"

Now:

ansis.reset('foo');
// "\x1b[0mfoo"

If you need a trailing reset, add it explicitly:

ansis.reset`foo ${ansis.red('bar')} baz` + ansis.reset();
// "\x1b[0mfoo \x1b[31mbar\x1b[39m baz\x1b[0m"

ansis.reset() without argument returns just the reset code \x1b[0m, which makes appending it easy.

2. strip() removes OSC 8 hyperlink sequences

strip() did not clear the OSC 8 sequences produced by link().
It now removes them and returns plain text:

ansis.strip(ansis.link('https://example.com', 'text'));
// "text"

3. No style leakage between instances with different color levels

Styles created on one Ansis instance could appear on another instance that was created with a different color level. That could give output rendered at the wrong color level.
Now, instances are isolated, so each one keeps its own styles and level.

import { Ansis } from 'ansis';

const noColor = new Ansis(0);
const color = new Ansis(1);

// Fixed: chained styles on `noColor` stay unstyled.
noColor.red.bold('foo');
// -> 'foo'

// Reference: a colored instance still renders the same chain with ANSI styles.
color.red.bold('foo');
// -> '\x1b[31m\x1b[1mfoo\x1b[22m\x1b[39m'

4. .extend() no longer affects other instances

Calling .extend() on one instance could override styles on other instances that use a different color level.
Now, the .extend() method stays local to the instance on which it is called.

import { Ansis } from 'ansis';

const trueColor = new Ansis(3);
const noColor = new Ansis(0);

trueColor.extend({
  pink: '#ff69b4',
});

// Fixed: `extend()` stays local to `trueColor`.
trueColor.red('foo');
// -> '\x1b[31mfoo\x1b[39m'

// Fixed: extending `trueColor` does not leak styles or color level into `noColor`.
noColor.red('foo');
// -> 'foo'

Features

• Added link(url, text?) for OSC 8 hyperlinks, supported by many terminal emulators, #44

• Added constructor overload to pass a mock globalThis object for controlled color auto-detection, #47

  import { Ansis } from 'ansis';
  
  const color = new Ansis({
    process: {
      env: { FORCE_COLOR: '1' },
      argv: ['node', 'app.js'],
      stdout: { isTTY: false },
      platform: 'linux',
    },
  });
  
  console.log(color.level); // 1

Bugfix

Fixed the handling edge cases for using ENV variables and CLI flags, #46

Feature

Added support named truecolors via ansis.extend() for both foreground and background.

Foreground methods are created from the provided color names, and matching background methods bg* are generated automatically.

output

Open in StackBlitz

Example:

import ansis from 'ansis';
import colorNames from 'css-color-names';

const color = ansis.extend(colorNames);

console.log(color.orange('Orange foreground'));
console.log(color.bgOrange('Orange background')); // auto-generated from "orange"

This release removes the last barrier for projects migrating from Chalk v4 that used named truecolors:

- chalk.keyword('orange')('text');
+ color.orange('text');

- chalk.bgKeyword('orange')('text');
+ color.bgOrange('text');

Ansis provides this feature with a simpler, more intuitive API.

Ansis v4 - Smaller package and cleaner API

Ansis v4 drops unused duplicate aliases and legacy baggage.
This release brings a stable and more compact ANSI library.
v4 is ~15.7% smaller than v3.17

Follow the migration guide to upgrade.

Breaking changes

1) Dropped support for Deno 1.x (EOL - October 9, 2024)

This version now supports Deno 2.0 and above.

2) Removed non-standard strike alias for strikethrough style

The legacy strike alias has been removed to clean up the API and stay consistent with ANSI style conventions.

• breaking

  The strike style was rarely (if ever) used and added unnecessary redundancy.

• breaking

  No usage of ansis.strike() was found in public GitHub repositories.

• breaking

  Other ANSI libraries use the standard strikethrough name exclusively.

3) Removed redundant aliases: grey, bgGrey, blackBright and bgBlackBright - use the standard gray and bgGray instead.

Holywar: gray vs grey vs blackBright

All these color names referred the same ANSI code.
However, keeping many separate names for the same color is too much for a small library.

Why gray only, without aliases?

ANSI codes for the gray color:

• breaking

  90 - officially "bright black" foreground (i.e., gray) in terminal specs.

• breaking

  100 - officially "bright black" background (i.e., bgGray) in terminal specs.

Ansis prefers the more intuitive and commonly used names: gray and bgGray.

• breaking

  ❌ blackBright, bgBlackBright - Spec-style names for "bright black", less intuitive, never used, awkward for practical use

4) Using 256-color functions

The following legacy method aliases have been removed:

These aliases were originally added for compatibility with Chalk.
Starting with this release, Ansis focuses on a cleaner and compact API, free from duplicated methods and legacy layers.

Why fg() and bg() are better than ansi256() and bgAnsi256()

Ansis has grown beyond being a Chalk-compatible alternative - it's now a modern and compact ANSI library with its own identity.

Clean API

• breaking

  ansis.fg(code) and ansis.bg(code) are shorter more elegant than ansis.ansi256(code) and ansis.bgAnsi256(code)

• breaking

  fg and bg clearly describe their purpose: setting foreground and background colors

• breaking

  These method names align with conventions used by many other color libraries

• breaking

  Introduced on Dec 2021, fg() and bg() are already being used in GitHub projects

• breaking

  Removing duplicates makes the API cleaner and more compact

5) Removed the unused AnsiColorsExtend type.

This type was intended to support extended theme colors, but it was never used in other projects.
If you relied on it in your own code (e.g. for typing custom styles), you can easily define it yourself.

6) Improved extend() method

The extend() method has been redesigned for better TypeScript support and flexibility.

Old behavior

extend<U extends string>(colors: Record<U, string>): asserts this is Ansis & Record<U, Ansis>;

• breaking

  Modifies the current instance in-place.

• breaking

  Returns void.

• breaking

  ✅ Worked with default instance:

  import ansis from 'ansis';
  
  ansis.extend({ pink: '#FF75D1' });
  console.log(ansis.pink('foo'));

• breaking

  ❌ Limitation - Did not work with newly created instances:

  import { Ansis } from 'ansis';
  
  const ansis = new Ansis();
  ansis.extend({ pink: '#FF75D1' }); // TS2775: Assertions require every name in the call target to be declared with an explicit type annotation.
  console.log(ansis.pink('Hello')); // TS2339: Property 'pink' does not exist

New behavior

extend<U extends string>(colors: Record<U, string >): Ansis & Record<U, Ansis>;

• Returns an extended instance with full type support.

• ✅ Works with both ansis and new Ansis():

  import antis from 'ansis';
  
  const colors = ansis.extend({ pink: '#FF75D1' });
  console.log(colors.pink('foo'));

  import { Ansis } from 'ansis';
  
  const ansis = new Ansis().extend({ pink: '#FF75D1' });
  console.log(ansis.pink('foo'));

Why this change?

TypeScript cannot widen the type of an existing variable when using asserts.
This means the old approach only worked for top-level constants like ansis, not new instances.
By returning the extended instance, the new approach enables full type inference in all scenarios.

Summary:

• breaking

  asserts version removed

• breaking

  extend() now returns an instance with extended types

• breaking

  Cleaner, safer, and fully compatible with all usage patterns

Features

1) Support escape sequences in tagged template literals

Ansis now treats tagged template literals the same way as normal strings, returning the same result as the standard function call.

Example with \n (newline, unescaped):

red('prev\nnext')
red`prev\nnext`

Output:

prev
next

Example with escaped backslash:

red('prev\\next')
red`prev\\next`

Output:

prev\next

2) Manually set the color level

Ansis automatically detects color support, but you can manually set the color level.
You can create a new instance of Ansis with the desired color level.

Disable colors:

import { Ansis } from 'ansis';

const ansis = new Ansis(0);
console.log(ansis.red`foo`); // Output: plain string, no ANSI codes

Use only basic 16 colors:

import { Ansis } from 'ansis';

const ansis = new Ansis(1);
console.log(ansis.hex('#FFAB40')`Orange`); // Output: fallback to yellowBright

3) Simplified CI color detection

Affects: In rare CI environments, output may fallback to 16 colors or black & white.

Ansis provides basic support for standard CI environments by checking the commonly used CI environment variable. In these environments, Ansis assumes support for at least 16 colors. If your code uses 256-color or truecolor, Ansis automatically fallback to 16 colors or to black and white if no color support is detected.

Ansis focuses on the most common scenarios, as specific CI environments are rarely used in practice. This approach keeps the package lightweight without including unnecessary detection logic.

GitHub Actions is still detected as supporting truecolor, as most Ansis users rely on GitHub CI.

In general, color output in CI environments is not critical and can gracefully fallback when needed.

The xterm-direct detection logic (introduced in v3.5.0) has been removed, as it's unnecessary for identifying truecolor-capable terminals.

Bug Fixes

Defaults to 16 colors for unknown color support

Ansis now defaults uses 16 colors if it cannot detect support for 256 colors or truecolor.

• Old behavior: Unknown terminal → used truecolor (could result in incorrect colors)

• New behavior: Unknown terminal → uses only 16 colors (ensures broad compatibility)

• Reduce the package size by ~200 bytes.

Cumulative Release v3.6.0 - v3.14.0

Features

• Added support for chromium-based browsers.\ Now you can use truecolor in the consoles of Chrome, Edge, Opera, Brave, Vivaldi and other Chromium-based browsers.
  Browsers that do not support ANSI codes will display black and white text.

• Added support for \n as a newline in template literals, e.g.: green`Hello\nWorld` renders:

  Hello
  World

• Function ansis.reset() returns the reset escape code \e[0m.

• Enforce a specific color support by a FORCE_COLOR value:

  • false - Disables colors

  • 0 - Disables colors

  • true (or unset) - Auto detects the supported colors (if no color detected, enforce truecolor)

  • 1 - Enables 16 colors

  • 2 - Enables 256 colors

  • 3 - Enables truecolor

• Removed undocumented pointless dummy function ansis(any).

import ansis from 'ansis';  
ansis('text'); // <= now will occur the ERROR TS2349: This expression is not callable.  

• Added support for legacy Node.js v14 (in package.json for npm was changed the engines to "node": ">=14").

• Micro optimisations for slight performance improvements.

Bug Fixes

• If the function argument is an empty string should be returned an empty string w/o escape codes:

  ansis.red('') => '', // returns empty string w/o escape codes

• Cast falsy values false and NaN to a string.
  In previous versions, the empty string '' was returned for falsy values.

• Functions with argument 0 , e.g. ansis.red(0), returning empty string '', now return colored value '0'

• Add support for legacy Node.js v14 (in package.json for npm was changed the engines to "node": ">=14")

• ansis.reset() returns the reset escape code \e[0m

• Micro optimisations for slight performance improvements

• Enforce a specific color support by a FORCE_COLOR value:

  • false - Disables colors

  • 0 - Disables colors

  • true (or unset) - Auto detects the supported colors (if no color detected, enforce truecolor)

  • 1 - Enables 16 colors

  • 2 - Enables 256 colors

  • 3 - Enables truecolor

• If the function argument is an empty string should be returned an empty string w/o escape codes:

  ansis.red('') => '', // returns empty string w/o escape codes

• Cast falsy values false, null, undefined, NaN to a string. In previous versions, the empty string '' was returned for falsy values.

• Functions with argument 0 , e.g. ansis.red(0), returning empty string '', now return colored value '0'

• Remove undocumented pointless dummy function ansis(any)

import ansis from 'ansis';
ansis('text'); // <= now will occur the ERROR TS2349: This expression is not callable.

Features

• Optimised the npm package size from 10.3 kB to 7.0 kB.

  Now, Ansis is the smallest yet most powerful library with rich functionality.
  A slightly smaller is picocolors (6.4 kB), but it offers only basic functionality.

• Added detection of the xterm-direct terminal as supportingtruecolor.

• Added support for the COLORTERM environment variable with the following values: truecolor, 24bit, ansi256, ansi (16 colors).

Bug Fixes (TypeScript)

• Fixed default import in TypeScript compiled with tsc:
  import ansis from 'ansis' now works so well as import * as ansis from 'ansis'.

• Fixed the TS2339: Property 'strip' does not exist on type when the tsc option module is node16.

3.5.0 (2024-12-26) release

• Add support the COLORTERM variable for values: truecolor, 24bit, ansi256, ansi (16 colors)

• Add support the xterm-direct terminal to detect the truecolor

• removed

  Remove detection environment variable GPG_TTY introduced in 3.5.0-beta.0 version, because it make no sense

• Default import in TypeScript, compiled with tsc: import ansis from 'ansis' now works so well as import * as ansis from 'ansis'

Cumulative Release v3.3.2 - v3.4.0

Bug Fixes

• Correct detect TTY on Windows platform.

• Correct detect TTY on Windows platform

Cumulative Release v3.0.1 - v3.1.1

Features

• Added detection of color support when using PM2 process manager.

Bug Fixes

• Correct interpret FORCE_COLOR=false or FORCE_COLOR=0 as force disable colors\ others values, e.g., FORCE_COLOR=true or FORCE_COLOR=1 - force enable colors.
  See force-color.org.

Features

• Added detection of color spaces support: TrueColor, 256 colors, 16 colors, no color (black & white).

• Added fallback for supported color space: truecolor —> 256 colors —> 16 colors —> no colors.

• Improved performance for the hex() function.

Breaking change

In the new major version 3.x are removed unused styles and methods.

⚠️ Warning

Before update, please check your code whether is used deleted styles and methods.

Support Node.js

Drop supports for Node <= 14. Minimal supported version is 15.0.0 (Released 2020-10-20).
In the theory the v3 can works with Node12, but we can't test it.

Deleted styles

The not widely supported styles are deleted:

• breaking

  faint (alias for dim), replace in your code with dim

• breaking

  doubleUnderline, replace in your code with underline

• breaking

  frame, replace in your code with underline

• breaking

  encircle, replace in your code with underline

• breaking

  overline, replace in your code with underline

Deleted methods

The methods are deleted:

• breaking

  ansi, replace in your code with ansi256 or fg

• breaking

  bgAnsi, replace in your code with bgAnsi256 or bg

Deleted clamp in functions

The clamp (0, 255) for the ANSI 256 codes and RGB values is removed, because is unused.
You should self check the function arguments.

The affected functions:

• breaking

  ansi256 and fg (alias to ansi256) - expected a code in the range 0 - 255

• breaking

  bgAnsi256 and bg (alias to bgAnsi256) - expected a code in the range0 - 255

• breaking

  rgb - expected r, g, b values in the range 0 - 255

• breaking

  bgRgb - expected r, g, b values in the range 0 - 255

Cumulative Release v2.0.1 - v2.3.0

Features

• Added detection of additional terminals, thanks @dse, colors.js:issue #42.

• Added supports the argument as number.

• Added bgGrey and bgGray aliases for bgBlackBright.

Bug Fixes

• Fixed index.d.ts to use function overload to make the tagged template have the correct type, #16.

• Fixed when could not be found a declaration file for module 'ansis'.

• Add supports the argument as number

• Add bgGrey and bgGray aliases for bgBlackBright

• Missing exports of ansis.strip() and ansis.export() functions (issue was introduced in v2.0.0)

Features

• Added support for Deno.

• Added support for Next.js edge runtime.

• Added NEW named import for ansis:

  import { red } from 'ansis';

  For example:
  NEW v2.x.x

  import ansis, { red } from 'ansis'; // default and named import
  ansis.red`error`;
  red`error`;

  OLD v1.5.x

  import ansis from 'ansis'; // default import
  import { red } from 'ansis/colors'; // named import
  ansis.red`error`;
  red`error`;

• Optimised named export into one file to avoid separate wraps files for CJS and ESM.

• Reduced the size of dist/ directory by 50%.

BREAKING CHANGE (TypeScript only)

The deprecated OLD named import from 'ansis/colors' still works, but using TypeScript can be occurred the error:

TS2307: Cannot find module ansis/colors ...

Solution: update your code, e.g.: import { red } from 'ansis/colors' --> import { red } from 'ansis'

DEPRECATIONS

• deprecated

  OLD named import import { red } from 'ansis/colors' is deprecated, use the NEW named import.

• deprecated

  The barely used ansi() function name is deprecated, use ansi256() or alias fg() instead.

• deprecated

  The barely used bgAnsi() function name is deprecated, use bgAnsi256() or alias bg() instead.

Cumulative Release v1.3.0 - v1.5.5

Features

• Added support for nested template literal syntax:

  console.log(red`red ${yellow`yellow ${green`green`} yellow`} red`)

• Added named export of colors with support for chained syntax:

  import { red, green, yellow } from 'ansis/colors';
  console.log(red.bold.underline`text`);

• Added extending of base colors with named custom truecolor:

  import ansis from 'ansis';
  ansis.extend({ orange: '#FFAB40' });
  console.log(ansis.orange.bold('text'));

• Added the strip() method to remove all ANSI codes from string

• Added support for both CommonJS and ESM

• Added aliases: .fg() for .ansi256() and .bg() for .bgAnsi256() methods

• Optimized distributed code size to less than 4 KB.

Bug Fixes

• Fixed visible style with nested template strings

• Set correct aliases for bgAnsi and fg methods by named export

• Regard the value of the environment variable FORCE_COLOR=0 to force disable colors

• Set correct aliases for bgAnsi and fg methods by named export

• Regard the value of the environment variable FORCE_COLOR=0 to force disable colors

• Add missing export for CJS mode in package.json