rich/docs/source/style.rst

.. _styles:


Styles
======

In various places in the Rich API you can set a "style" which defines the color of the text and various attributes such as bold, italic etc. A style may be given as a string containing a *style definition* or as in instance of a :class:`~rich.style.Style` class.


Defining Styles
---------------

A style definition is a string containing one or more words to set colors and attributes.

To specify a foreground color use one of the 256 :ref:`appendix-colors`. For example, to print "Hello" in magenta::

    console.print("Hello", style="magenta")

You may also use the color's number (an integer between 0 and 255). The following will give the equivalent output::

    console.print("Hello", style="5")

Alteratively you can use a CSS-like syntax to specify a color with a "#" followed by three pairs of hex characters, or in RGB form with three decimal integers. The following two lines both print "Hello" in the same color (purple)::

    console.print("Hello", style="#af00ff")
    console.print("Hello", style="rgb(175,0,255)")

The hex and rgb forms allow you to select from the full *truecolor* set of 16.7 million colors.

.. note::
    Some terminals only support 256 colors. Rich will attempt to pick the closest color it can if your color isn't available.


By itself, a color will change the *foreground* color. To specify a *background* color precede the color with the word "on". For example, the following prints text in red on a white background::

    console.print("DANGER!", style="white on red")

You can set a style attribute by adding one or more of the following words:

* ``"bold"`` For bold text.
* ``"blink"`` For text that flashes (use this one sparingly).
* ``"conceal"`` For *concealed* text (not supported by many terminals).
* ``"italic"`` For italic text.
* ``"reverse"`` For text with foreground and background colors reversed.
* ``"strike"`` For text with a line through it.
* ``"underline"`` For underlined text.

Style attributes and colors may be used in combination with each other. For example::

    console.print("Danger, Will Robinson!", style="blink bold red underline on white")


Style Class
-----------

Ultimately the style definition is parsed and an instance of a :class:`~rich.style.Style` class is created. If you prefer, you can use the Style class in place of the style definition. Here's an example::

    from rich.style import Style
    console.print("Danger, Will Robinson!", style=Style(color="red", blink=True, bold=True)

It is slightly quicker to construct a Style class like this, since a style definition takes a little time to parse -- but only on the first call, as Rich will cache any style definitions it parses.

You can parse a style definition explicitly with the :meth:`~rich.style.Style.parse` method.


Style Themes
------------

If you re-use styles it can be a maintenance headache if you ever want to modify an attribute or color -- you would have to change every line where the style is used. Rich provides a :class:`rich.theme.Theme` class which you can use to define custom styles that you can refer to by name. That way you only need update your styles in one place.

Style themes can make your code more semantic, for instance a style called ``"warning"`` better expresses intent that ``"italic magenta underline"``.

To use a style theme, construct a :class:`rich.theme.Theme` instance and pass it to the :class:`~rich.console.Console` constructor. Here's an example::

    from rich.console import Console
    from rich.theme import Theme
    custom_theme = Theme({
        "info" : Style.parse("dim cyan"),
        "warning": Style.parse("magenta"),
        "danger": Style.parse("bold red")
    })
    console = Console(theme=custom_theme)
    console.print("This is information", style="info")
    console.print("Something terrible happened!", style="danger")

You can also use these custom styles via markup. For example::

    console.print("[warning]The pod bay doors are locked[/warning]")

If you prefer you can write your styles in an external config file rather than in Python. Here's an example of the format::

    [styles]
    info = dim cyan
    warning = magenta
    danger = bold red

You can read these files with the :meth:`~rich.theme.Theme.read` method.