Crate nanocolor 

Minimal, zero-dependency terminal color and text styling for Rust.

nanocolor gives you ANSI 16-color support (foreground and background), common text styles, conditional styling, and decorative masking — all through a chainable trait-based API. Zero dependencies, single file, under 400 lines.

Quick Start

Import Colorize and call color/style methods on strings, numbers, or booleans:

use nanocolor::Colorize;

println!("{}", "error".red().bold());
println!("{}", "warning".yellow().on_black());
println!("{}", 42.cyan());
println!("{}", true.green().italic());

Styling Any Type

Colorize is implemented for &str, String, and all common primitives (i8–i128, u8–u128, f32, f64, bool, char). For custom Display types, use the style() helper:

use nanocolor::{Colorize, style};

// Primitives work directly
let count = 99.red().bold();
let pi = 3.14_f64.green();

// Custom types use style()
let msg = style(format!("v{}.{}", 2, 0)).cyan();

Conditional Styling

Use .whenever() to enable or disable styling per-value, independent of the global color state:

use nanocolor::Colorize;

let is_important = true;
println!("{}", "alert".red().bold().whenever(is_important));

// .whenever(false) always strips ANSI codes
println!("{}", "plain".red().whenever(false)); // prints "plain"

When .whenever() is not called, styling follows the global colors_enabled() state. If called multiple times, the last call wins.

Decorative Masking

Use .mask() to mark decorative values (emoji, symbols) that should disappear entirely when styling is inactive:

use nanocolor::Colorize;

// When colors are on:  "✓ passed"
// When colors are off: " passed"
print!("{}", "✓ ".green().mask());
println!("passed");

Masked values render normally when styling is active, and as an empty string when styling is inactive (colors disabled or .whenever(false)).

Automatic Color Detection

nanocolor automatically detects whether stdout is a TTY. When output is piped to a file or another program, ANSI codes are skipped and plain text is emitted.

The NO_COLOR environment variable is also respected — set it to any non-empty value to disable colors globally.

Global Enable / Disable

Use enable() and disable() to override auto-detection from code:

// CLI app with a --no-color flag
nanocolor::disable();

This is useful for CLI apps that parse their own flags. Call it once early in main() and all styled output respects it automatically.

Available Colors

Standard	Bright
black()	bright_black()
red()	bright_red()
green()	bright_green()
yellow()	bright_yellow()
blue()	bright_blue()
magenta()	bright_magenta()
cyan()	bright_cyan()
white()	bright_white()

All colors have background variants with the on_ prefix (e.g. on_red(), on_bright_cyan()).

Available Styles

bold(), dim(), italic(), underline(), blink(), rapid_blink(), reverse(), hidden(), strikethrough(), overline()

Structs

StyledString

A string with accumulated ANSI color and style information.

Enums

Color

The 16 standard ANSI terminal colors.

Style

Text style modifiers (bold, dim, italic, underline, strikethrough).

Traits

Colorize

Functions

clear_colors_override

Clear the test override so the real detection is used.

colors_enabled

Returns whether ANSI color output is currently enabled.

disable

Globally disable ANSI color output, overriding auto-detection.

enable

Globally enable ANSI color output, overriding auto-detection.

set_colors_override

Force colors on or off for testing purposes.

style

Wraps any Display type in a StyledString for chainable styling.

with_colors_override

Run a closure with the color override set, holding a lock to prevent races with other tests that also use color overrides.