cell_text: Helper for defining custom text styles for table cells

In gt: Easily Create Presentation-Ready Display Tables

Helper for defining custom text styles for table cells

Description

This helper function can be used with tab_style(), which itself allows for the setting of custom styles to one or more cells. We can also define several styles within a single call of cell_text() and tab_style() will reliably apply those styles to the targeted element.

Usage

cell_text(
  color = NULL,
  font = NULL,
  size = NULL,
  align = NULL,
  v_align = NULL,
  style = NULL,
  weight = NULL,
  stretch = NULL,
  decorate = NULL,
  transform = NULL,
  whitespace = NULL,
  indent = NULL
)

Arguments

color	Text color ⁠scalar<character>⁠ // default: NULL (optional) The text color can be modified through the color argument.
font	Font (or collection of fonts) used for text ⁠vector<character>⁠ // default: NULL (optional) The font or collection of fonts (subsequent font names are) used as fallbacks.
size	Text size ⁠scalar<numeric|integer|character>⁠ // default: NULL (optional) The size of the font. Can be provided as a number that is assumed to represent px values (or could be wrapped in the px() helper function). We can also use one of the following absolute size keywords: "xx-small", "x-small", "small", "medium", "large", "x-large", or "xx-large".
align	Text alignment ⁠scalar<character>⁠ // default: NULL (optional) The text in a cell can be horizontally aligned though one of the following options: "center", "left", "right", or "justify".
v_align	Vertical alignment ⁠scalar<character>⁠ // default: NULL (optional) The vertical alignment of the text in the cell can be modified through the options "middle", "top", or "bottom".
style	Text style ⁠scalar<character>⁠ // default: NULL (optional) Can be one of either "normal", "italic", or "oblique".
weight	Font weight ⁠scalar<character|numeric|integer>⁠ // default: NULL (optional) The weight of the font can be modified thorough a text-based option such as "normal", "bold", "lighter", "bolder", or, a numeric value between 1 and 1000, inclusive. Note that only variable fonts may support the numeric mapping of weight.
stretch	Stretch text ⁠scalar<character>⁠ // default: NULL (optional) Allows for text to either be condensed or expanded. We can use one of the following text-based keywords to describe the degree of condensation/expansion: "ultra-condensed", "extra-condensed", "condensed", "semi-condensed", "normal", "semi-expanded", "expanded", "extra-expanded", or "ultra-expanded". Alternatively, we can supply percentage values from ⁠0\%⁠ to ⁠200\%⁠, inclusive. Negative percentage values are not allowed.
decorate	Decorate text ⁠scalar<character>⁠ // default: NULL (optional) Allows for text decoration effect to be applied. Here, we can use "overline", "line-through", or "underline".
transform	Transform text ⁠scalar<character>⁠ // default: NULL (optional) Allows for the transformation of text. Options are "uppercase", "lowercase", or "capitalize".
whitespace	White-space options ⁠scalar<character>⁠ // default: NULL (optional) A white-space preservation option. By default, runs of white-space will be collapsed into single spaces but several options exist to govern how white-space is collapsed and how lines might wrap at soft-wrap opportunities. The options are "normal", "nowrap", "pre", "pre-wrap", "pre-line", and "break-spaces".
indent	Text indentation ⁠scalar<numeric|integer|character>⁠ // default: NULL (optional) The indentation of the text. Can be provided as a number that is assumed to represent px values (or could be wrapped in the px() helper function). Alternatively, this can be given as a percentage (easily constructed with pct()).

Value

A list object of class cell_styles.

Examples

Let's use the exibble dataset to create a simple, two-column gt table (keeping only the num and currency columns). With tab_style() (called twice), we'll selectively add style to the values formatted with fmt_number(). We do this by using cell_text() in the style argument of tab_style().

exibble |>
  dplyr::select(num, currency) |>
  gt() |>
  fmt_number(decimals = 1) |>
  tab_style(
    style = cell_text(weight = "bold"),
    locations = cells_body(
      columns = num,
      rows = num >= 5000
    )
  ) |>
  tab_style(
    style = cell_text(style = "italic"),
    locations = cells_body(
      columns = currency,
      rows = currency < 100
    )
  )

Function ID

8-25

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other helper functions: adjust_luminance(), cell_borders(), cell_fill(), currency(), default_fonts(), escape_latex(), from_column(), google_font(), gt_latex_dependencies(), html(), md(), nanoplot_options(), pct(), px(), random_id(), row_group(), stub(), system_fonts(), unit_conversion()

gt documentation built on April 12, 2025, 1:26 a.m.