Kroma Documentation

Meet Kroma, a lightweight and powerful library for terminal output in Python. It allows you to set colors, text formatting, and more with ease.

Links

• GitHub Repository
• Documentation (this page)
• PyPI Project Page

Installation

You can install Kroma using pip:

pip install kroma

HTML Colors and HEX Codes

Using Named HTML Colors

Kroma provides access to all of the standard HTML color names through the HTMLColors enum. You can use these named colors with the style() function to set foreground and background colors.

import kroma

print(kroma.style(
    "This is black text on a spring green background.",
    background=kroma.HTMLColors.SPRINGGREEN,
    foreground=kroma.HTMLColors.BLACK
))

Output:

Partial Color Styling

You can set only the background or foreground color to keep the other as default:

import kroma

print(kroma.style(
    "This is normal text with a maroon background.",
    background=kroma.HTMLColors.MAROON
))

print(kroma.style(
    "This is goldenrod text on a normal background.",
    foreground=kroma.HTMLColors.GOLDENROD
))

Output:

Custom HEX Colors

The style() function also accepts custom HEX color codes:

import kroma

print(kroma.style(
    "This is text with a custom background and foreground.",
    background="#000094",
    foreground="#8CFF7F"
))

Output:

ANSI Colors

For terminals that don’t support True Color, use ANSI colors instead:

import kroma

# Bright blue text on red background
print(kroma.style(
    "This is bright blue text on a red background.",
    background=kroma.ANSIColors.RED,
    foreground=kroma.ANSIColors.BRIGHT_BLUE
))

Output:

Note: Kroma’s unified style() function automatically detects whether you’re using ANSI or HTML colors and processes them accordingly. You cannot mix ANSI and HTML colors in the same call - this will raise a MixedColorTypesError.

Custom Styles

For frequently used styles, you can create reusable style objects using CustomStyle. This allows you to define a style once and apply it to multiple strings without having to specify the style parameters.

Creating and Using CustomStyle

The CustomStyle class works with both HTML colors and ANSI colors, using the same parameters as the style() function except without the text parameter:

import kroma

# Define the Style
reusable_style = kroma.CustomStyle(
    foreground=kroma.HTMLColors.DARKKHAKI,
    background=kroma.HTMLColors.NAVY,
    bold=True
)

# Use the Style
print(reusable_style("This is some text styled with a CustomStyle!"))
print(reusable_style("Here's another line with the same styling."))
print(reusable_style("Yet another styled line."))

Output:

ANSI CustomStyle

You can also create custom styles for ANSI colors. As shown in this example, custom styles can be useful for things like warnings and errors.

import kroma

# Define the Style
warning_style = kroma.CustomStyle(
    foreground=kroma.ANSIColors.BRIGHT_YELLOW,
    background=kroma.ANSIColors.RED,
    bold=True
)

# Use the Style
print(warning_style("Warning: This is important!"))
print(warning_style("Another warning message."))

Output:

Palettes

Kroma supports color palettes, such as Gruvbox, Solarized, and Bootstrap, which are perfect if you want a nice looking terminal output without having to pick individual colors.

import kroma

# (optional: set a palette alias for easier access)
palette = kroma.palettes.Solarized

# IMPORTANT: you must enable the palette to set the proper background and foreground colors.
# with alias:
palette.enable()
# without alias:
kroma.palettes.Solarized.enable()

# with alias:
print(palette.debug("This is a debug message in the Solarized palette"))
print(palette.error("This is an error message in the Solarized palette"))

# without alias:
print(kroma.palettes.Solarized.info("This is an info message in the Solarized palette"))
print(kroma.palettes.Solarized.success("This is a success message in the Solarized palette"))

Output:

Available Palettes and Methods

All palettes support the following methods:

• info(text) - Informational messages
• debug(text) - Debug messages
• warning(text) - Warning messages
• error(text) - Error messages
• critical(text) - Critical error messages
• success(text) - Success messages

Available palettes:

• kroma.palettes.Gruvbox - Popular retro groove color scheme
• kroma.palettes.Solarized - Low-contrast scheme by Ethan Schoonover
• kroma.palettes.Bootstrap - Colors from the Bootstrap CSS framework

If you want more control over the formatting of the text, you can combine it with the style() function. However, this gets pretty messy, so it’s recommended to just use the palette’s built-in functions for simple use cases, or make your own custom styles if the palettes aren’t sufficient.

import kroma

kroma.palettes.Solarized.enable()

print(kroma.palettes.Solarized.info(kroma.style("This is an underlined and bold info message in the Solarized palette", bold=True, underline=True)))

Output:

Color Manipulation

Swapping Colors

You can swap foreground and background colors at runtime:

import kroma

print(kroma.style(
    "This is text with a bisque background and a blue violet foreground.\n",
    foreground=kroma.HTMLColors.BLUEVIOLET,
    background=kroma.HTMLColors.BISQUE,
))

print(kroma.style(
    "This is the same text with the foreground and background swapped.",
    foreground=kroma.HTMLColors.BLUEVIOLET,
    background=kroma.HTMLColors.BISQUE,
    swap_foreground_background=True
))

Output:

Lightening and Darkening Colors

Kroma also provides utility functions to manipulate color brightness at runtime. It works with both HTML colors and HEX codes, however it does not work with ANSI colors.

import kroma

print(kroma.style(
    "This is text with colors manipulated at runtime.",
    foreground=kroma.lighten(kroma.HTMLColors.GAINSBORO, 10),
    background=kroma.darken("#2F4F4F", 20)
))

Output:

• kroma.lighten(color, amount) - Makes a color lighter
• kroma.darken(color, amount) - Makes a color darker

Gradients

Kroma provides powerful gradient tools that allows you to create smooth gradients across text. This feature works with HTML colors and HEX codes.

Basic Two-Color Gradients

Using kroma.gradient(), you can create a gradient between two colors.

import kroma

print(kroma.gradient(
    "This text has a gradient from red to blue!",
    stops=(kroma.HTMLColors.RED, kroma.HTMLColors.BLUE)
))

You can also use HEX colors in place of the HTMLColors enum for finer control.

import kroma

print(kroma.gradient(
    "This text has a gradient from #FF5733 to #33FFCE!",
    stops=("#FF5733", "#33FFCE")
))

Multi-Stop Gradients

You can also create complex gradients with multiple color stops.

import kroma

print(kroma.gradient(
    "This is a rainbow gradient across the text!",
    stops=(
        kroma.HTMLColors.RED,
        kroma.HTMLColors.ORANGE, 
        kroma.HTMLColors.YELLOW,
        kroma.HTMLColors.GREEN,
        kroma.HTMLColors.BLUE,
        kroma.HTMLColors.PURPLE
    )
))

Just like with two-color gradients, you can also use HEX colors for multi-stop gradients.

Background Gradients

Apply gradients to the background instead of the foreground by setting the style_type parameter to kroma.StyleType.BACKGROUND.

import kroma

print(kroma.gradient(
    "This has a background gradient!",
    stops=(kroma.HTMLColors.DARKBLUE, kroma.HTMLColors.LIGHTBLUE),
    style_type=kroma.StyleType.BACKGROUND
))

Custom Gradient Styles

For reusable gradient styles, use CustomGradient - this works similarly to CustomStyle:

import kroma

# Define the CustomGradient
sunset_gradient = kroma.CustomGradient(
    stops=(kroma.HTMLColors.ORANGE, kroma.HTMLColors.RED, kroma.HTMLColors.PURPLE),
    style_type=kroma.StyleType.FOREGROUND
)

# Apply the gradient
print(sunset_gradient("This text has a sunset-like gradient."))
print(sunset_gradient("So does this text!"))
print(sunset_gradient("And this one too!"))

Multi-Line Gradient Handling

Kroma’s gradient function handles multi-line text by treating each line as a separate entity, causing each line to have the same gradient instead of the gradient spanning the lines.

import kroma

print(kroma.gradient(
    "Line 1 with gradient\nLine 2 with gradient\nLine 3 with gradient",
    stops=(kroma.HTMLColors.CYAN, kroma.HTMLColors.MAGENTA)
))

Text Formatting

The style() function supports text formatting options:

Available Formatting Options

• bold=True - Bold text
• italic=True - Italic text
• underline=True - Underlined text
• strikethrough=True - Strikethrough text

Examples

import kroma

# All formatting options combined
print(kroma.style(
    "This is bold, italic, underlined, and strikethrough text.",
    bold=True,
    italic=True,
    underline=True,
    strikethrough=True
))

# Individual formatting options
print(kroma.style("This is bold text.", bold=True))
print(kroma.style("This is underlined text.", underline=True))
print(kroma.style(
    "This is italic and strikethrough text.",
    italic=True,
    strikethrough=True
))

Output:

Combining Colors and Formatting

You can combine text formatting with colors in a single call:

import kroma

print(kroma.style(
    "This is bold and italic text with colors.",
    foreground=kroma.ANSIColors.MAGENTA,
    bold=True,
    italic=True
))

Output:

API Reference

Functions

kroma.style(text, **kwargs)

kroma.gradient(text, *, stops, style_type=StyleType.FOREGROUND, steps=None)

kroma.lighten(color, percentage)

kroma.darken(color, percentage)

Classes

kroma.CustomGradient(*, stops, style_type=StyleType.FOREGROUND, steps=None)

kroma.CustomStyle(**kwargs)

Utility Functions and Variables

kroma.ansi_supported

Exceptions

kroma.MixedColorTypesError

import kroma

# This will raise MixedColorTypesError
kroma.style("text", foreground=kroma.ANSIColors.RED, background=kroma.HTMLColors.BLUE)

Enums

kroma.StyleType

kroma.HTMLColors

kroma.ANSIColors

Terminal Compatibility

• HTML Colors: Require True Color terminal support (most modern terminals)
• ANSI Colors: Compatible with virtually all terminals
• Text Formatting: Bold and underline are widely supported, italic and strikethrough have slightly less support.

Choose the appropriate color system based on your target environment’s capabilities. The unified style() function makes it easy to switch between color types without changing your code structure, just change the background and foreground parameters.