ANSI Color and Emphasis Options in fmtlib: The Complete Guide

fmtlib provides three specialized enums—fmt::color for 256 X11 colors, fmt::terminal_color for 4-bit terminal colors with bright variants, and fmt::emphasis for bitwise text styling flags—that combine into a fmt::text_style object for automatic ANSI terminal output.

The fmtlib/fmt repository implements a type-safe, header-only API for terminal styling that eliminates manual escape sequence management. Understanding the ANSI color and emphasis options in fmtlib enables developers to produce rich console output across platforms while maintaining clean, readable code.

Terminal Styling APIs in include/fmt/color.h

All color and emphasis functionality is exposed through include/fmt/color.h. This header defines three distinct enums covering the full ANSI capability spectrum, from legacy 16-color support to modern 24-bit RGB values.

256-Color X11 Palette with fmt::color

The fmt::color enum (defined starting at line 16) contains named X11 web colors stored as 24-bit RGB values. The palette spans from alice_blue and antique_white through steel_blue and yellow_green, providing access to the full 256-color space supported by modern terminal emulators.

4-Bit Standard Colors with fmt::terminal_color

For broad compatibility, the fmt::terminal_color enum (line 160) exposes the 16 standard ANSI colors. The enum lists eight base colors—black, red, green, yellow, blue, magenta, cyan, white—paired with their bright variants: bright_black, bright_red, bright_green, bright_yellow, bright_blue, bright_magenta, bright_cyan, and bright_white.

Bitwise Emphasis Flags with fmt::emphasis

The fmt::emphasis enum (line 179) defines style flags using bitwise values that support OR-combination:

• bold (1)
• faint (1 << 1)
• italic (1 << 2)
• underline (1 << 3)
• blink (1 << 4)
• reverse (1 << 5)
• conceal (1 << 6)
• strikethrough (1 << 7)

Composing Styles with fg(), bg(), and text_style

The library packs foreground colors, background colors, and emphasis flags into a fmt::text_style object. The fg() and bg() helper functions convert color enums into style components, while emphasis flags combine using the bitwise OR operator.

// Bright red text, underlined, on cyan background
fmt::print(
    fmt::emphasis::underline | 
    fg(fmt::terminal_color::bright_red) | 
    bg(fmt::terminal_color::cyan),
    "Important message\n");

For X11 palette colors, pass fmt::color values to the same helpers:

// Steel blue foreground with italic emphasis
fmt::print(fg(fmt::color::steel_blue) | fmt::emphasis::italic,
           "Styled with steel-blue and italic\n");

Compound emphasis styles are created by OR-ing multiple flags:

auto style = fmt::emphasis::bold | fmt::emphasis::blink;
fmt::print(style, "Blinking bold text\n");

ANSI Escape Sequence Handling

When the destination stream is a color-capable terminal, fmtlib emits standard ANSI escape sequences (\033[...m) to render the styles. If the output is redirected to a file or piped to a non-terminal device, the library automatically strips color codes, producing plain text without requiring conditional logic in user code.

Source Code Organization

The color system is organized across three key locations in the fmtlib repository:

• include/fmt/color.h — Core definitions for color, terminal_color, and emphasis enums, plus the text_style infrastructure
• doc/api.md — High-level documentation for the Color API
• test/color-test.cc — Unit tests verifying correct ANSI sequence generation and emphasis handling

Summary

• Three enum types in include/fmt/color.h provide complete ANSI coverage: fmt::color (24-bit X11), fmt::terminal_color (16 standard colors), and fmt::emphasis (8 bitwise style flags)
• Helper functions fg() and bg() convert color values into fmt::text_style objects compatible with fmt::print and fmt::format
• Bitwise composition allows combining emphasis flags such as bold | underline | italic for complex styling
• Automatic terminal detection ensures ANSI codes are stripped when outputting to files or non-terminal streams

Frequently Asked Questions

What is the difference between fmt::color and fmt::terminal_color?

fmt::color (line 16) provides 256 named X11 colors using 24-bit RGB values for modern terminals, while fmt::terminal_color (line 160) offers the 16 standard 4-bit ANSI colors including bright variants for maximum compatibility with legacy terminal emulators.

Can I combine multiple emphasis styles like bold and underline?

Yes. The fmt::emphasis enum uses bitwise flags that support OR-combination. You can chain styles such as fmt::emphasis::bold | fmt::emphasis::underline to apply multiple effects simultaneously, as implemented in include/fmt/color.h at line 179.

How does fmtlib handle color output when redirecting to a file?

According to the source implementation, fmtlib automatically detects whether the output stream is a terminal. When redirecting to files or pipes, the library strips ANSI escape sequences automatically, ensuring clean plain-text output without requiring code changes.

Where are the color definitions located in the fmtlib repository?

All ANSI color and emphasis definitions reside in include/fmt/color.h, specifically at lines 16 (X11 colors), 160 (terminal colors), and 179 (emphasis flags). Additional documentation exists in doc/api.md, with comprehensive tests validating the behavior in test/color-test.cc.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}