AnsiUtils 1.0.6

AnsiUtils

A lightweight .NET library for working with ANSI console colors, text formatting, and terminal control. AnsiUtils uses an intuitive tag-based system where you embed formatting codes directly in your strings using [tagname] syntax.

Features

• Tag-based formatting - Embed [red], [bold], [underline] etc. directly in strings
• Standard and bright ANSI colors (foreground and background)
• RGB and grayscale color support for modern terminals
• Text styles (bold, underline, blink, inverse)
• Cursor movement and screen control
• Console window title control
• Taskbar/tab progress indicators (ConEmu, Windows Terminal, Ghostty)
• ANSI-aware string operations (substring, padding, centering, etc.)
• Text wrapping and columnar formatting with ANSI preservation
• Rich UI components via AnsiText class (tables, progress bars, boxes, lists, spinners)

Installation

dotnet add package AnsiUtils

Quick Start

using AnsiUtils;

// Initialize ANSI support (intercepts Console.Out to process tags)
AnsiConsole.Initialize();

// Use embedded tags directly in your strings
Console.WriteLine("[red]Error:[normal] Something went wrong!");
Console.WriteLine("[green]Success![normal] Operation completed.");
Console.WriteLine("[bold][yellow]Warning:[normal] Check your input.");

// Combine colors, backgrounds, and styles
Console.WriteLine("[white][bgblue] Status: Online [normal]");
Console.WriteLine("[underline][cyan]Click here for more info[normal]");

// Set the console window title
Console.WriteLine("[title:My Application]");

Tag Reference

Color Tags

Foreground Colors

Bright Foreground Colors

Use [bright___], [br___], or [bright-___] prefix:

• [brightred], [brred], [bright-red]
• [brightgreen], [brgreen], [bright-green]
• [brightyellow], [bryellow], [bright-yellow]
• [brightblue], [brblue], [bright-blue]
• [brightpurple], [brpurple], [bright-purple]
• [brightcyan], [brcyan], [bright-cyan]
• [brightwhite], [brwhite], [bright-white]
• [brightblack], [brblack], [bright-black]

Background Colors

Bright backgrounds follow the same pattern: [bgbrightred], [bgbrgreen], etc.

Grayscale Colors (24 levels)

• Foreground: [gray00] to [gray23] (or [grey00] to [grey23])
• Background: [bggray00] to [bggray23] (or [bggrey00] to [bggrey23])

gray00 is darkest (near black), gray23 is lightest (near white).

Extended Colors

8-bit RGB (values 0-5 for each component):

Console.WriteLine("[fg:5:0:0]Bright red[normal]");      // Foreground
Console.WriteLine("[bg:0:0:5]Blue background[normal]"); // Background

24-bit True Color (hex values):

Console.WriteLine("[fg:ff:80:00]Orange text[normal]");
Console.WriteLine("[bg:00:ff:80]Mint background[normal]");

Style Tags

Cursor Movement Tags

Screen Control Tags

Progress Tags (Taskbar/Tab)

These use OSC 9;4 sequences, supported by ConEmu, Windows Terminal, and Ghostty.

Special Tags

Console Title

Set the terminal window title using either the tag or method:

// Using the tag
Console.WriteLine("[title:My Application - Running]");

// Using the method
AnsiConsole.SetTitle("My Application - Idle");

// Dynamic title updates (e.g., for progress)
for (int i = 0; i <= 100; i += 10)
{
    AnsiConsole.SetTitle($"Processing: {i}%");
    Thread.Sleep(100);
}

Taskbar/Tab Progress

Show progress in the terminal's taskbar button or tab. Supported by ConEmu, Windows Terminal, and Ghostty.

// Set progress percentage (0-100)
AnsiConsole.SetProgress(75);

// Indeterminate (animated) progress
AnsiConsole.SetProgressIndeterminate();

// Error state (red) with optional percentage
AnsiConsole.SetProgressError(50);   // 50% in error state
AnsiConsole.SetProgressError();     // Error, no percentage

// Warning state (yellow) with optional percentage
AnsiConsole.SetProgressWarning(80); // 80% in warning state
AnsiConsole.SetProgressWarning();   // Warning, no percentage

// Clear the progress indicator
AnsiConsole.ClearProgress();

// Or use tags directly
Console.WriteLine("[progress:50]");         // 50% progress
Console.WriteLine("[progress]");            // Indeterminate
Console.WriteLine("[progress:error:75]");   // Error at 75%
Console.WriteLine("[progress:warn:60]");    // Warning at 60%
Console.WriteLine("[progress:off]");        // Clear

AnsiText.CreateProgressBar() automatically embeds a [progress:N] tag, so the taskbar updates alongside the visual bar:

for (int i = 0; i <= 100; i += 10)
{
    Console.Write($"\r{AnsiText.CreateProgressBar(i, 30)}");
    Thread.Sleep(200);
}
AnsiConsole.ClearProgress();

Cursor and Screen Control Methods

In addition to tags, you can use direct methods:

AnsiConsole.ClearScreen();
AnsiConsole.CursorPosition(row: 5, column: 10);
AnsiConsole.CursorUp(2);
AnsiConsole.CursorDown(3);
AnsiConsole.CursorLeft(5);
AnsiConsole.CursorRight(5);
AnsiConsole.ClearLine();
AnsiConsole.Delay(500);
AnsiConsole.SetTitle("My App");

Creating Animations

Combine cursor movement, delays, and colors:

Console.WriteLine("[clearscreen][home][blue]Loading:[normal]");
Console.WriteLine("[hidecursor]");

for (int i = 0; i <= 100; i += 5)
{
    Console.Write($"[pos:1:2][clearlineforward]");
    int blocks = i / 5;
    Console.Write($"[green]{new string('█', blocks)}[normal] {i}%");
    Console.Write("[delay:100]");
}

Console.WriteLine("\n[showcursor][green]Complete![normal]");

Typewriter Effect

AnsiConsole.TypeWriter("[green]This text appears character by character.[normal]");
AnsiConsole.TypeWriter("[yellow]Slower typing...[normal]", delayMs: 100);

ANSI-Aware String Operations

Standard string operations don't account for ANSI codes. AnsiUtils provides ANSI-aware alternatives:

string text = "[red]Hello[normal] [blue]World[normal]";

// Get visible length (ignoring ANSI codes)
int len = text.AnsiLength();  // Returns 11, not 41

// Substring that preserves formatting
string part = text.AnsiSubstring(0, 5);  // "[red]Hello[normal]"

// Find text position (ignoring ANSI codes)
int pos = text.AnsiIndexOf("World");

// Padding and alignment
string centered = text.AnsiCenter(30);
string leftPad = text.AnsiPadLeft(30, '.');
string rightPad = text.AnsiPadRight(30, '.');

// Text wrapping
var lines = text.WrapText(maxWidth: 40);

// Columnize a list of items
var items = new List<string> { "[red]Item 1[normal]", "[green]Item 2[normal]" };
var columns = items.Columnize(numColumns: 2, maxWidth: 60);

Fluent API (Extension Methods)

For those who prefer method chaining, AnsiUtils also provides extension methods:

using AnsiUtils;

// Colors
Console.WriteLine("Red text".Red());
Console.WriteLine("Green text".Green());
Console.WriteLine("Blue on yellow".Blue().OnYellow());

// Bright colors
Console.WriteLine("Bright magenta".BrightMagenta());

// Styles
Console.WriteLine("Bold text".Bold());
Console.WriteLine("Underlined".Underline());
Console.WriteLine("Blinking".Blink());
Console.WriteLine("Inverse".Inverse());

// RGB colors
Console.WriteLine("Custom color".Rgb(135, 206, 235));
Console.WriteLine("Custom background".BgRgb(255, 192, 203));

// Chaining
Console.WriteLine("Styled text".Red().Bold().Underline().OnWhite());

Advanced Text Formatting with AnsiText

The AnsiText class provides rich UI components:

Progress Bars

var progress = AnsiText.CreateProgressBar(75.0);
Console.WriteLine(progress);  // ██████████████████████████████░░░░░░░░░░ 75.0%

// Customized
var custom = AnsiText.CreateProgressBar(
    percentage: 50.0,
    width: 30,
    fillChar: '■',
    emptyChar: '□',
    label: "Loading",
    showPercentage: true,
    fillColor: "[bright][blue]",
    emptyColor: "[dim][gray]"
);

Bordered Boxes

var box = AnsiText.CreateBox("Hello, World!", "Greeting", AnsiText.BoxStyle.Rounded);
foreach (var line in box)
    Console.WriteLine(line);

// Box styles: Single, Double, Rounded, Ascii

Tables

var users = new List<User> {
    new User { Name = "Alice", Age = 30 },
    new User { Name = "Bob", Age = 25 }
};

var table = AnsiText.FormatTable(users, new[] { "Name", "Age" }, maxWidth: 60);
foreach (var row in table)
    Console.WriteLine(row);

// Dictionary tables
var config = new Dictionary<string, string> {
    { "Status", "[green]Online[normal]" },
    { "Version", "2.1.0" }
};
var dictTable = AnsiText.FormatDictionary(config);

Lists

var items = new[] { "First", "Second", "Third" };

var bullets = AnsiText.FormatList(items, AnsiText.ListStyle.Bullets);
var numbered = AnsiText.FormatList(items, AnsiText.ListStyle.Numbers);
var checkboxes = AnsiText.FormatList(items, AnsiText.ListStyle.Checkboxes);
var custom = AnsiText.FormatList(items, AnsiText.ListStyle.Custom,
    customBullet: "★", bulletColor: "[yellow]");

Separators

var sep = AnsiText.CreateSeparator(50);  // ──────────────────────────────────────────────────

var labeled = AnsiText.CreateSeparator(40, '─', "SECTION", AnsiText.SeparatorStyle.Centered);
// ─────────────── SECTION ───────────────

Spinners and Status Indicators

// Spinner frames for animations
var frame = AnsiText.CreateSpinner(frameIndex, AnsiText.SpinnerStyle.Unicode);

// Status indicators
Console.WriteLine(AnsiText.CreateStatusIndicator(AnsiText.StatusType.Success, "Done!"));
Console.WriteLine(AnsiText.CreateStatusIndicator(AnsiText.StatusType.Error, "Failed"));
Console.WriteLine(AnsiText.CreateStatusIndicator(AnsiText.StatusType.Warning, "Check this"));
Console.WriteLine(AnsiText.CreateStatusIndicator(AnsiText.StatusType.Info, "FYI"));

Controlling ANSI Processing

Use CodeOptions flags to enable or disable specific feature categories:

// Enable specific features only
AnsiConsole.Options = AnsiConsole.CodeOptions.Colors | AnsiConsole.CodeOptions.Backgrounds;

// Enable all features (default)
AnsiConsole.Options = AnsiConsole.CodeOptions.All;

// Disable all ANSI processing (pass through raw text)
AnsiConsole.Options = AnsiConsole.CodeOptions.Ignore;

// Disable just progress indicators
AnsiConsole.Options = AnsiConsole.CodeOptions.All & ~AnsiConsole.CodeOptions.Progress;

Cleanup

// Restore original Console.Out when done (optional)
AnsiConsole.Restore();

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.