ANSI Text #

A library for adding rich formatting to terminal text using ANSI escape codes. It supports bold, italic, underline, and other SGR styles, multiple color palettes including truecolor, and clickable hyperlinks through the OSC 8 standard. The API is fluent, IDE-friendly, and allows enabling or disabling formatting globally.

Usage #

To add ANSI styling to text, wrap the string in an AnsiText object:

final text = AnsiText('Hello, world');

The AnsiText object can now be formatted by applying styling to it:

text
  ..apply(Styles.markup.bold)
  ..apply(Styles.color.text.bright.yellow)
  ..apply(Styles.color.background.red);

The text can be output to the terminal by printing it or writing it to stdout or stderr. Printing automatically calls toString() on the AnsiText object, applying all requested ANSI escape codes and appending a terminating reset sequence:

print(text);

When applying multiple style attributes to a single AnsiText object, the applyAll method can be convenient:

AnsiText('Hello, world')
..applyAll({
    Styles.markup.bold,
    Styles.color.text.bright.yellow,
    Styles.color.background.red,
});

Note that the Styles class is structured in such a way that it provides out-of-the-box command completion in an IDE, allowing for fast entry and compile-time checking.

Shorthand methods #

Various shorthand methods for frequently used styles are provided. For example, instead of typing:

text..apply(Styles.markup.bold);

one may also use:

text..bold();

See shorthand.dart for the complete list of shorthand methods.

Hyperlinks #

AnsiText supports clickable hyperlinks in terminals that implement the OSC 8 standard. A hyperlink can be applied to a string using the hyperlink method:

final text = AnsiText('Source code')
  ..hyperlink(Uri.parse('https://github.com/drillster/ansi_text'));

When printed to a compatible terminal:

print(text);

the text "Source code" will be a clickable link pointing to https://github.com/drillster/ansi_text.

Combining hyperlinks with styles

Hyperlinks can be combined with SGR styling:

final text = AnsiText('Important link')
  ..bold()
  ..color(Styles.color.text.bright.yellow)
  ..hyperlink(Uri.parse('https://github.com/drillster/ansi_text'));

print(text);

All styles are applied inside the hyperlink sequence — the order of applying styles and hyperlinks does not affect the output.

Notes

• Only one hyperlink can be applied per AnsiText instance. Applying hyperlink multiple times overwrites the previous value.
• Empty hyperlinks (Uri() or Uri.parse('')) are ignored and do not emit OSC 8 sequences.
• Hyperlinks require terminal support. Terminals that do not implement OSC 8 will display the text normally without a link.
• Hyperlinks can be chained alongside other style methods for fluent usage.

Color palettes #

This library supports three color palettes:

1. The 8 standard colors + 8 brighter versions
2. The 256-color (8-bit) color system, extending the standard colors with 216 RGB colors and 24 grayscales
3. The 24-bit RGB true color palette, comprising of over 16 million colors

The standard colors are implemented as color names. The "bright" variants of the standard colors require a bright. prefix. For example:

AnsiText('Hello, world')
  ..apply(Styles.color.text.yellow) // standard color
  ..apply(Styles.color.background.bright.red) // bright variant

The 216 RGB colors from the 8-bit color scheme are available through the rgb(int red, int green, int blue) method. The values of each component must be between 0 and 5 (inclusive). For example:

AnsiText('Hello, world')
  ..apply(Styles.color.text.rgb(1, 2, 3))
  ..apply(Styles.color.background.rgb(3, 2, 1));

For grayscales there is the gray(int lightness) method. The value must be between 0 and 23 (inclusive), with 0 being the darkest and 23 the lightest. Example:

AnsiText('Hello, world')
  ..apply(Styles.color.text.gray(3))
  ..apply(Styles.color.background.gray(18));

In order to output text or background in 24-bit true color, use the trueColor(int red, int green, int blue) method. The values of each component must be between 0 and 255 (inclusive). Example:

AnsiText('Hello, world')
  ..apply(Styles.color.text.trueColor(60, 120, 180))
  ..apply(Styles.color.background.trueColor(180, 120, 60));

The library does not automatically detect terminal color support. Typically, terminals advertise support via the TERM and COLORTERM environment variables. For example, TERM=xterm-256color indicates 256-color support, while COLORTERM=truecolor indicates 24-bit true color support.

Similarly, there is no guarantee that all of the markup options work as expected. Not all terminal emulators support all of the provided markup styles.

Global configuration #

By default, ansi_text will always output ANSI escape codes, but there is an on/off switch should you wish to suppress the use of markup, colors, and hyperlinks globally:

AnsiText.enabled = false; // suppress markup, colors, and hyperlinks

Setting AnsiText.enabled to false is useful in those cases where the output stream does not support ANSI markup. For the best user experience, you can sync the library with the user's terminal capabilities using dart:io:

import 'dart:io';
import 'package:ansi_text/ansi_text.dart';

void main() {
  // Automatically disable colors if the terminal doesn't support them
  AnsiText.enabled = stdout.hasTerminal && stdout.supportsAnsiEscapes;
}

Examples #

See example/example.dart for a reasonably exhaustive overview of colors and markup. Running it produces the following output: