Skip to content

Text

rich_gradient.Text (available as rich_gradient.text.Text) extends rich.text.Text with foreground and background gradients while preserving every feature from the base class (markup, spans, justification, overflow handling, highlighting, etc.). Anywhere you would normally construct a rich.text.Text, you can drop in this subclass to gain gradient support.

Basic usage

from rich.console import Console
from rich_gradient import Text

console = Console()
console.print(
    Text(
        "Gradient text with zero fuss.",
        colors=["#38bdf8", "#a855f7", "#f97316"],
        style="bold",
    )
)

The output above is generated by examples/text_quickstart.py and captured as docs/img/text-quickstart.svg.

Picking color stops

Pass colors to control foreground stops. Every item can be a CSS color name, a hex string, an RGB tuple, a rich.color.Color, or a ColorTriplet. When colors is empty the class falls back to Spectrum with the requested hues. Set rainbow=True to use the full rainbow palette.

Palette showcase

from rich_gradient.spectrum import Spectrum
from rich_gradient import Text

Text("Explicit stops", colors=["#0ea5e9", "#a855f7", "#f97316"])
Text("Auto hues", hues=6)  # draws from Spectrum(hues=6)
Text("Spectrum seed", colors=Spectrum(hues=5, seed=7).triplets)

Behind the scenes rich-gradient relies on rich-color-ext so three-digit hex codes and CSS color names resolve without extra work.

Background gradients

Use bgcolors to gradient-fill the background independently. Single background colors are treated as a solid fill, while multiple stops interpolate smoothly.

Background gradients

Text(
    "Foreground & background gradient",
    colors=["#2563eb", "#ec4899"],
    bgcolors=["#0f172a", "#1f2937"],
)
Text("Rainbow with solid background", rainbow=True, bgcolors=["#111827"])
Text("Background-only gradient", colors=["#f1f5f9"], bgcolors=["#22d3ee", "#f97316"])

Set Text(..., markup=False) when you want to treat the input literally rather than parsing Rich markup. You can still call .stylize() or provide spans explicitly if you need fine-grained styling.

Round-tripping to rich.text.Text

Need to hand control back to Rich? Call .as_rich() to return a standard rich.text.Text instance with the gradient-applied content and spans:

text = Text("Gradient once, regular Text later.", hues=5)
rich_text = text.as_rich()

This is useful when you want to serialize the output or reuse it in renderables that expect a plain Text.