Ansis
ANSI color library - Docs
ANSI color lib
ANSI color library - Docs
level
property to get the detected color support level:Release v4.
Ansis v4 drops legacy baggage and unused artifacts. This release brings a stable and more compact ANSI library. v4.0.0 is 12.4% smaller than v3.17.0.
Removed unused and rarely used aliases for gray
and bgGray
:
grey
, bgGrey
- British spelling, uncommon, redundant aliases for gray
and bgGray
blackBright
, bgBlackBright
- Spec-style names for "bright black", less intuitive, rarely used, and awkward in practiceSupporting three separate names for the same color is too much and introduces ambiguity into the API.
Replace deprecated aliases with the preferred standard names:
- ansis.grey('text')
- ansis.blackBright('text')
+ ansis.gray('text')
- ansis.bgGrey('text')
- ansis.bgBlackBright('text')
+ ansis.bgGray('text')
The unused AnsiColorsExtend
type has been removed.
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.
If you previously used the AnsiColorsExtend
type, you’ll now need to define a custom utility type.
Here's an example how to update your code:
- import ansis, { AnsiColorsExtend } from 'ansis';
+ import ansis, { AnsiColors } from 'ansis';
+ type AnsiColorsExtend<T extends string> = AnsiColors | (T & Record<never, never>);
const myTheme = {
orange: '#FFAB40',
};
// Extend ansis with custom colors
const colors = ansis.extend(myTheme);
// Custom logger supporting both built-in and extended styles
const log = (style: AnsiColorsExtend<keyof typeof myTheme>, message: string) => {
console.log(colors[style](message));
}
log('orange', 'message'); // extended color
This change ensures compatibility with the latest version of Ansis, where AnsiColorsExtend
is no longer available.
The following legacy method aliases have been removed:
❌ Removed Method | ✅ Use Instead |
---|---|
ansi256(code) |
fg(code) |
bgAnsi256(code) |
bg(code) |
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.
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.
Clear and expressive API
ansis.fg(code)
and ansis.bg(code)
are shorter more elegant than ansis.ansi256(code)
and ansis.bgAnsi256(code)
fg
and bg
clearly describe their purpose: setting foreground and background colorsfg()
and bg()
are already being used in GitHub projectsUpdating from a previous version is simple:
import ansis from 'ansis';
- ansis.ansi256(196)('Error')
+ ansis.fg(196)('Error')
- ansis.bgAnsi256(21)('Info')
+ ansis.bg(21)('Info')
Alternatively, to keep compatibility with existing code:
- import { ansi256, bgAnsi256 } from 'ansis';
+ import { fg as ansi256, bg as bgAnsi256 } from 'ansis';
ansi256(196)('Error')
bgAnsi256(21)('Info')
No other changes are required - everything else remains fully compatible.
extend()
methodThe extend()
method has been redesigned for better TypeScript support and flexibility.
extend<U extends string>(colors: Record<U, string | P>): asserts this is Ansis & Record<U, Ansis>;
void
.✅ Worked with default instance:
import ansis from 'ansis';
ansis.extend({ pink: '#FF75D1' });
console.log(ansis.pink('foo'));
❌ Limitation - Did not work with newly created instances:
import { Ansis } from 'ansis';
const ansis = new Ansis();
ansis.extend({ pink: '#FF75D1' });
console.log(ansis.pink('Hello')); // TS2339: Property 'pink' does not exist
extend<U extends string>(colors: Record<U, string | P>): Ansis & Record<U, Ansis>;
✅ Works with both ansis
and new Ansis()
:
import ansis, { Ansis } from 'ansis';
const colors = ansis.extend({ pink: '#FF75D1' });
console.log(colors.pink('foo'));
const custom = new Ansis().extend({ apple: '#4FA83D' });
console.log(custom.apple('bar'));
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:
asserts
version removedextend()
now returns a new instance with extended typesThe new extend()
method now returns an extended instance instead of modifying the original in-place.
To migrate, assign the result of extend()
to a new variable (avoid reassigning the original instance):
import ansis from 'ansis';
- ansis.extend({ pink: '#FF75D1' });
+ const theme = ansis.extend({ pink: '#FF75D1' });
- console.log(ansis.pink('foo'));
+ console.log(theme.pink('foo'));
Or
import { Ansis } from 'ansis';
- ansis.extend({ pink: '#FF75D1' });
+ const ansis = new Ansis().extend({ pink: '#FF75D1' });
console.log(ansis.pink('foo'));
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 custom = new Ansis(0);
console.log(custom.red`foo`); // Output: plain string, no ANSI codes
Use only basic colors:
import { Ansis } from 'ansis';
const custom = new Ansis(1);
console.log(custom.hex('#FFAB40')`Orange`); // Output: fallback to yellowBright
xterm-direct
terminfo check for truecolor support (not a breaking change)The xterm-direct
detection logic (introduced in v3.5.0
) has been removed, as it's unnecessary for identifying truecolor-capable terminals.
Note
No terminal emulator sets
TERM=xterm-direct
by default. Modern terminals, including KDE Konsole, typically useTERM=xterm-256color
along withCOLORTERM=truecolor
to indicate truecolor support.
Ansis now defaults uses 16 colors if it cannot detect support for 256 colors or truecolor.
Note
This is not a breaking change. Ansis gracefully interpolates higher color depths (truecolor and 256 colors) down to 16 colors when using
fg()
,hex()
orrgb()
. To explicitly enable truecolor, set the environment variableCOLORTERM=24bit
orFORCE_COLOR=3
.
strike
style (alias for strikethrough
)The legacy strike
alias has been removed to clean up the API and stay consistent with ANSI style conventions.
strike
style was rarely (if ever) used and added unnecessary redundancy.ansis.strike()
was found in public GitHub repositories.strikethrough
name exclusively.If you're using strike
style, replace it with strikethrough
.
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
Deprecated.
typescript
< 5.6
to fix TS2526 error:A 'this' type is available only in a non-static member of a class or interface.
NOTE: If you are already using TypeScript >= 5.6, this update is not required.tsup
bundler.Skip this version number.
\n
as a newline in template literals, e.g.: green`Hello\nWorld`
renders:Hello
World
engines
to "node": ">=14"
)ansis.reset()
returns the reset escape code \e[0m
null
and undefined
values to empty string as before v3.7.0
, #25feat: enforce a specific color support by a FORCE_COLOR
value:
fix: 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
false
, null
, undefined
, NaN
to a string.
In previous versions, the empty string ''
was returned for falsy values.0
, e.g. ansis.red(0)
, returning empty string ''
, now return colored value '0'
feat: remove undocumented pointless dummy function ansis(any)
[!WARNING] This is not a BREAKING CHANGE because it was never officially documented!
import ansis from 'ansis'; ansis('text'); // <= now will occur the ERROR TS2349: This expression is not callable.
This warning applies only to projects where Chalk was replaced with Ansis and something like
chalk('text')
was used.Just replace
ansis('text')
with'text'
.The
ansis('text')
function was a dummy and did nothing except return the same input string.
chore: update license to current date
module
is node16
COLORTERM
variable for values: truecolor
, 24bit
, ansi256
, ansi
(16 colors)xterm-direct
terminal to detect the truecolorGPG_TTY
introduced in 3.5.0-beta.0
version, because it make no sensetsc
:
import ansis from 'ansis'
now works so well as import * as ansis from 'ansis'
xterm-direct
terminal as supported the truecolorCOLORTERM
variable for values: truecolor
, 24bit
, ansi256
, ansi
(16 colors)COLORTERM
with examplesGPG_TTY
to detect it as isTTY
.
NOTE: in release v3.5.1 was removed as needles.tsc
:
import ansis from 'ansis'
now works so well as import * as ansis from 'ansis'
type
with dynamic properties instead of the interface
tsc
, swc
and esbuild
compilerskolorist
packageindex.d.ts
to reduce the size by ~200 bytes,old
named import DEPRECATED in v2.0.0
(2023-11-03).
If you update the package from v1.x
to v3.3.0
then check your code:\
ESM- import { red } from 'ansis/colors';
+ import { red } from 'ansis';
CJS- const { red } = require('ansis/colors');
+ const { red } = require('ansis');
package.json
for npm packageansis.isSupported()
method to detect color supporthex()
functionIn 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.
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.
v3.3.0
)ESM
- import { red } from 'ansis/colors';
+ import { red } from 'ansis';
CJS
- const { red } = require('ansis/colors');
+ const { red } = require('ansis');
The not widely supported
styles are deleted:
faint
(alias for dim), replace in your code with dim
doubleUnderline
, replace in your code with underline
frame
, replace in your code with underline
encircle
, replace in your code with underline
overline
, replace in your code with underline
The methods are deleted:
ansi
, replace in your code with fg
bgAnsi
, replace in your code with bg
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:
fg
- expected a code in the range 0 - 255
bg
- expected a code in the range0 - 255
rgb
- expected r, g, b values in the range 0 - 255
bgRgb
- expected r, g, b values in the range 0 - 255
number
npm run compare
bgGrey
and bgGray
aliases for bgBlackBright
edge
runtimeansis
:\
NEW named import: import { red } from 'ansis'
.\
If you use TypeScript
and your IDE show the error: TS2307: Cannot find module ansis/colors
,\
then you should use the new syntax,
update you code: import { red } from 'ansis/colors'
--> import { red } from 'ansis'
.import { red } from 'ansis/colors'
is deprecated, use the NEW named importansi
use fg
bgAnsi
use bg
edge
runtimeconsole.log(red`red ${yellow`yellow ${green`green`} yellow`} red`)
import { red, green, yellow } from 'ansis/colors';
console.log(red.bold.underline`text`);
import ansis from 'ansis';
ansis.extend({ orange: '#FFAB40' });
console.log(ansis.orange.bold('text'));
index.d.ts
AnsiStyles
, AnsiColors
and AnsiColorsExtend types in index.d.ts
4 KB
grey
for gray
const ansis = require('ansis').default;
--> const ansis = require('ansis');
.fg()
for .ansi256()
and .bg()
for .bgAnsi256()
methods.
DEPRECATED methods: ansi
, ansi256
, bgAnsi
,bgAnsi256
- use fg
and bg
instead.NO_COLOR
FORCE_COLOR
and flags --no-color
--color
ansi
for ansi256
and bgAnsi
for bgAnsi256
open
and close
properties for each styleFirst release