A lightweight, header-only C++17 library for colorful and well-formatted console output.
ColormaCpp brings ANSI colors, text styles, and convenient {}-based formatting together in one small library. It has no third-party dependencies and works with standard output streams such as std::cout, std::cerr, and std::ostringstream.
Color your console. Keep your C++ simple.
- 16 foreground colors and 16 background colors, including bright variants.
- Bold, italic, underline, reverse, and reset styles.
- Inline color/style changes inside format strings.
{}replacement fields with numeric and string formatting options.- Stream-based and
std::coutconvenience overloads. - Automatic, forced, and disabled color modes.
- Automatic terminal detection,
NO_COLOR, andTERM=dumbhandling. - Windows virtual-terminal processing when writing to a supported console.
- Header-only, C++17, dependency-free.
- CMake target with install/export support.
#include <colorma/colorma.hpp>
#include <iostream>
int main() {
using colorma::Color;
using colorma::Style;
colorma::println(
std::cout,
"{}Hello {}World{}!",
Color::green,
Style::bold + Color::bright_red,
Style::reset);
colorma::println(
std::cout,
"{}PI = {:.15f}{}",
Color::bright_cyan,
3.141592653589793,
Style::reset);
}The first line prints Hello in green, World in bold bright red, and ! in the terminal's default style. The second prints PI to 15 digits after the decimal point.
- C++17-compatible compiler.
- CMake 3.16 or newer (only needed for the CMake workflow).
- No external libraries.
Tested in this project with GCC 14, Clang 17, and CMake on Linux. CI is configured for GCC, Clang, AppleClang, and MSVC. Windows behavior should be validated in your target terminal/console environment.
Copy the include/ directory into your project and include:
#include <colorma/colorma.hpp>A compatibility header is also provided:
#include <Colorma.hpp># From the root of the downloaded or cloned repository:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
ctest --test-dir build --output-on-failureRun one of the example programs, for example:
./build/examples/colorma_example_02_inline_formattingOn Windows, the executable is typically under build\examples\Release\ when using a multi-configuration generator.
After installation, another CMake project can use the exported target:
find_package(ColormaCpp CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE ColormaCpp::ColormaCpp)Install the library from a build directory with:
cmake --install build --prefix /your/install/prefixusing colorma::Color;
using colorma::Style;
colorma::print(std::cout, "Working... ", Color::yellow);
colorma::println(std::cout, "done", Color::bright_green, std::nullopt, {Style::bold});
// std::cout convenience overloads:
colorma::println("Success", Color::green);
colorma::print("Still on this line... ", Color::cyan);
colorma::println("next line", Color::white);The original colorize, stream-based print/println, and their original parameter order are retained.
Each format field consumes exactly one argument. A Color, Style, TextStyle, or BackgroundColor argument changes the style state rather than inserting visible text.
colorma::println(
std::cout,
"{}SUCCESS:{} The operation completed in {} ms.",
Color::bright_green,
Style::reset,
125);
colorma::println(
std::cout,
"{}Warning{}: disk space is low.",
Style::bold + Color::black + colorma::on(Color::bright_yellow),
Style::reset);Styling is reset at segment boundaries, so ANSI formatting does not accidentally leak into later console output.
colorma::println(
std::cout,
"{} BUILD OK {}",
Color::black + colorma::on(Color::bright_green) + Style::bold,
Style::reset);Use colorma::on(Color::blue) to create a background-color token.
colorma::println(std::cout, colorma::ColorMode::automatic,
"{}Auto{}", Color::green, Style::reset);
colorma::println(std::cout, colorma::ColorMode::always,
"{}Forced ANSI{}", Color::yellow, Style::reset);
colorma::println(std::cout, colorma::ColorMode::never,
"Plain output");automaticemits ANSI only when the destination is recognized as an interactive terminal and color is not disabled by the environment.alwaysforces ANSI sequences. Use this when you explicitly want ANSI output, including when writing to a file or captured stream.neveremits plain text.
NO_COLOR (when set to a non-empty value) and TERM=dumb disable automatic color output. These environment checks do not override explicit always mode.
ColormaCpp supports automatic sequential fields ({}), escaped braces ({{ and }}), and a deliberately small formatting grammar. Positional fields and named fields are not supported.
| Format | Meaning |
|---|---|
{} |
Default formatting |
{:d} |
Decimal integer |
{:x} / {:X} |
Lowercase / uppercase hexadecimal |
{:o} |
Octal integer |
{:c} |
Integer code converted to a single-byte character |
{:.3f} |
Fixed-point with 3 digits after the decimal point |
{:e} / {:E} |
Scientific notation |
{:g} / {:G} |
General floating-point notation |
{:a} / {:A} |
Hexadecimal floating-point notation |
{:05d} |
Integer width 5, zero-filled |
{:+d} |
Show a plus sign for non-negative numbers |
{:#x} |
Alternate hexadecimal form (0x prefix) |
{:>10} |
Right-aligned, width 10 |
{:<10} |
Left-aligned, width 10 |
{:^10} |
Center-aligned, width 10 |
{:*>10} |
Right-aligned, * fill character |
{:.5s} |
String precision: keep at most 5 bytes |
{{text}} |
Literal {text} |
Format flags are type-checked. Unsupported specifications, unmatched braces, missing arguments, and unused arguments throw colorma::format_error before the formatted result is written to the destination stream.
See docs/FORMAT_SPECIFIERS.md for details and examples/ for complete programs.
| Example | Demonstrates |
|---|---|
01_quick_start.cpp |
Basic foreground colors and convenience overloads |
02_inline_formatting.cpp |
Inline tokens, styles, and numeric formatting |
03_status_dashboard.cpp |
Colored status output |
04_colors_and_styles.cpp |
The 16-color palette, text styles, and backgrounds |
05_pi_and_numbers.cpp |
PI, precision, and ordinary iostream formatting |
06_color_modes.cpp |
Automatic, forced, and disabled color modes |
ColormaCpp/
├── .github/ # CI, issue templates, pull request template
├── cmake/ # CMake package configuration
├── docs/ # API and format reference
├── examples/ # Standalone example programs
├── include/
│ ├── colorma/colorma.hpp # Main public header
│ └── Colorma.hpp # Backward-compatible include
├── tests/ # Automated tests
├── CMakeLists.txt
├── LICENSE
├── CHANGELOG.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
└── README.md
Bug reports, focused improvements, and documentation updates are welcome. Please read CONTRIBUTING.md before opening a pull request.
ColormaCpp is licensed under the MIT License. See LICENSE.