Skip to main content

Crate colored_text

Crate colored_text 

Source
Expand description

A library for adding colors and styles to terminal text output.

This library provides a simple and intuitive way to add colors and styles to text in terminal applications. It works with both string literals and owned strings, and supports various text colors, background colors, and text styles.

Styling is composed before rendering, so chained calls behave predictably: the most recent foreground/background color wins, text styles accumulate, and ANSI escape codes are emitted only once when the styled value is displayed.

§Examples

use colored_text::Colorize;

// Basic color usage
println!("{}", "Red text".red());
println!("{}", "Blue background".on_blue());
println!("{}", "Bright black text".bright_black());
println!("{}", "Bright black background".on_bright_black());

// Combining styles
println!("{}", "Bold green text".green().bold());

// Using with format! macro
let name = "World";
println!("{}", format!("Hello, {}!", name.blue().bold()));

// ANSI 256, RGB, and Hex colors
println!("{}", "ANSI 256 color".ansi256(208));
println!("{}", "ANSI 256 background".on_ansi256(236));
println!("{}", "RGB color".rgb(255, 128, 0));
println!("{}", "Hex color".hex("#ff8000"));

// Clearing styles
println!("{}", "Plain text".red().bold().clear());

§Features

  • Basic colors (red, green, blue, yellow, etc.)
  • Background colors
  • Bright color variants
  • Text styles (bold, dim, italic, underline)
  • ANSI 256-color foreground and background support
  • RGB, HSL, and Hex color support
  • Terminal color capability detection
  • RGB, HSL, and Hex degradation when truecolor is unavailable
  • Composed style chaining
  • Works with format! macro
  • Explicit runtime color and color-depth modes

§Input Handling

  • RGB values must be in range 0-255 (enforced at compile time via u8 type)
  • Attempting to use RGB values > 255 will result in a compile error
  • ANSI 256-color indexes must be in range 0-255 (enforced at compile time via u8 type)
  • .color256(index) and .on_color256(index) are aliases for .ansi256(index) and .on_ansi256(index)
  • Hex color codes can be provided with or without the # prefix in 3-digit shorthand or 6-digit full form
  • Invalid hex codes (wrong length or invalid characters) return plain unstyled text
  • All color methods are guaranteed to return a valid string, never panicking
use colored_text::Colorize;

// Valid hex codes (with or without #)
println!("{}", "Valid hex".hex("#ff8000"));
println!("{}", "Also valid".hex("ff8000"));
println!("{}", "Shorthand".hex("#f80"));

// Invalid hex codes return plain text
println!("{}", "Invalid hex".hex("xyz")); // Returns plain text
println!("{}", "Wrong length".hex("#1234")); // Returns plain text

§Runtime Color Control

The crate supports three runtime modes via ColorMode:

The NO_COLOR environment variable disables styling in all modes, including when FORCE_COLOR or an explicit ColorDepthMode is set. ColorMode::Never also always disables color output.

For normal targets such as RenderTarget::Stdout, RenderTarget::Stderr, and RenderTarget::Terminal, color depth is resolved from environment variables and the current configuration after color output is enabled. Positive ColorDepthMode values select the depth to use; they do not by themselves bypass ColorMode::Auto non-terminal suppression. For RenderTarget::Capabilities, the supplied TerminalCapabilities are used as-is except for the hard disables: NO_COLOR, ColorMode::Never, and ColorDepthMode::NoColor.

use colored_text::{ColorDepthMode, ColorMode, Colorize, ColorizeConfig};

ColorizeConfig::set_color_mode(ColorMode::Always);
println!("{}", "Always colored".red());

ColorizeConfig::set_color_depth_mode(ColorDepthMode::Ansi256);
println!("{}", "ANSI 256 orange".rgb(255, 128, 0));

ColorizeConfig::set_color_mode(ColorMode::Never);
println!("{}", "Never colored".red());

When you need Auto mode to follow a destination other than stdout, use StyledText::render with a RenderTarget.

use colored_text::{ColorizeConfig, RenderTarget};

let caps = ColorizeConfig::terminal_capabilities(RenderTarget::Stdout);
println!("stdout color level: {:?}", caps.color_level);

§Compatibility with 0.4.1

Since 0.4.1, Colorize has gained required trait methods for bright foreground and bright background colors. Most users rely on the blanket impl<T: std::fmt::Display> Colorize for T and are unaffected. Downstream crates with manual impl Colorize for ... blocks must implement the new methods.

§Note

Colors and styles are implemented using ANSI escape codes, which are supported by most modern terminals. Capability detection is heuristic and environment-based; the crate does not use terminfo, termcap, active terminal queries, WinAPI console enablement, CLI parsing, or runtime dependencies. If color output is disabled by policy, the text is displayed without styling.

Structs§

ColorizeConfig
Configuration for controlling runtime color behavior.
StyledText
A styled text value that composes colors and text attributes before render.
TerminalCapabilities
Resolved terminal capability information for an output target.

Enums§

ColorDepthMode
Runtime color depth override for rendered output.
ColorLevel
Resolved color support level for an output target.
ColorMode
Runtime color policy for rendered output.
RenderTarget
Output target used when rendering styled text explicitly.

Traits§

Colorize
Trait for turning values into styled terminal text.