themes {cli}R Documentation

CLI themes

Description

CLI elements can be styled via a CSS-like language of selectors and properties. Only a small subset of CSS3 is supported, and a lot visual properties cannot be implemented on a terminal, so these will be ignored as well.

Adding themes

The style of an element is calculated from themes from four sources. These form a stack, and the themes on the top of the stack take precedence, over themes in the bottom.

  1. The cli package has a built-in theme. This is always active. See builtin_theme().

  2. When an app object is created via start_app(), the caller can specify a theme, that is added to theme stack. If no theme is specified for start_app(), the content of the cli.theme option is used. Removed when the corresponding app stops.

  3. The user may speficy a theme in the cli.user_theme option. This is added to the stack after the app's theme (step 2.), so it can override its settings. Removed when the app that added it stops.

  4. Themes specified explicitly in cli_div() elements. These are removed from the theme stack, when the corresponding cli_div() elements are closed.

Writing themes

A theme is a named list of lists. The name of each entry is a CSS selector. Only a subset of CSS is supported:

The content of a theme list entry is another named list, where the names are CSS properties, e.g. color, or font-weight or margin-left, and the list entries themselves define the values of the properties. See builtin_theme() and simple_theme() for examples.

Formatter callbacks

For flexibility, themes may also define formatter functions, with property name fmt. These will be called once the other styles are applied to an element. They are only called on elements that produce output, i.e. not on container elements.

Supported properties

Right now only a limited set of properties are supported. These include left, right, top and bottom margins, background and foreground colors, bold and italic fonts, underlined text. The before and after properties are supported to insert text before and after the content of the element.

The current list of properties:

More properties might be added later. If you think that a property is not applied properly to an element, please open an issue about it in the cli issue tracker.

Examples

Color of headings, that are only active in paragraphs with an 'output' class:

list(
  "par.output h1" = list("background-color" = "red", color = "#e0e0e0"),
  "par.output h2" = list("background-color" = "orange", color = "#e0e0e0"),
  "par.output h3" = list("background-color" = "blue", color = "#e0e0e0")
)

Create a custom alert type:

list(
  ".alert-start" = list(before = symbol$play),
  ".alert-stop"  = list(before = symbol$stop)
)

[Package cli version 3.0.1 Index]