# ANSI Color and Emphasis Options in fmtlib: The Complete Guide

> Explore fmtlib's ANSI color and emphasis options. Learn to use fmt::color, fmt::terminal_color, and fmt::emphasis to style your terminal output effectively.

- Repository: [Hello World Foundation/fmt](https://github.com/fmtlib/fmt)
- Tags: deep-dive
- Published: 2026-09-10

---

**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`](https://github.com/fmtlib/fmt/blob/main/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.

```cpp
// 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:

```cpp
// 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:

```cpp
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`](https://github.com/fmtlib/fmt/blob/main/include/fmt/color.h)** — Core definitions for `color`, `terminal_color`, and `emphasis` enums, plus the `text_style` infrastructure
- **[`doc/api.md`](https://github.com/fmtlib/fmt/blob/main/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`](https://github.com/fmtlib/fmt/blob/main/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`](https://github.com/fmtlib/fmt/blob/main/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`](https://github.com/fmtlib/fmt/blob/main/include/fmt/color.h), specifically at lines 16 (X11 colors), 160 (terminal colors), and 179 (emphasis flags). Additional documentation exists in [`doc/api.md`](https://github.com/fmtlib/fmt/blob/main/doc/api.md), with comprehensive tests validating the behavior in `test/color-test.cc`.