text_replace: Perform highly targeted text replacement with a regex pattern

In gt: Easily Create Presentation-Ready Display Tables

Perform highly targeted text replacement with a regex pattern

Description

text_replace() provides a specialized interface for replacing text fragments in table cells with literal text. You need to ensure that you're targeting the appropriate cells with the locations argument. Once that is done, the remaining two values to supply are the regex pattern (pattern) and the replacement for all matched text (replacement).

Usage

text_replace(data, pattern, replacement, locations = cells_body())

Arguments

data	The gt table data object ⁠obj:<gt_tbl>⁠ // required This is the gt table object that is commonly created through use of the gt() function.
pattern	Regex pattern to match with ⁠scalar<character>⁠ // required A regex pattern used to target text fragments in the cells resolved in locations.
replacement	Replacement text ⁠scalar<character>⁠ // required The replacement text for any matched text fragments.
locations	Locations to target <locations expressions> // default: cells_body() The cell or set of cells to be associated with the text transformation. Only cells_column_spanners(), cells_column_labels(), cells_row_groups(), cells_stub(), and cells_body() can be used here. We can enclose several of these calls within a list() if we wish to make the transformation happen at different locations.

Value

An object of class gt_tbl.

Examples

Use the metro dataset to create a gt table. With cols_merge(), we'll merge the name and caption columns together but only if caption doesn't have an NA value (the special pattern syntax of "{1}<<({2})>>" takes care of this). This merged content is now part of the name column. We'd like to modify this further wherever there is text in parentheses: (1) make that text italicized, and (2) introduce a line break before the text in parentheses. We can do this with text_replace(). The pattern value of "\\((.*?)\\)" will match on text between parentheses, and the inner "(.*?)" is a capture group. The replacement value of "<br>(<em>\\1</em>)" puts the capture group text "\\1" within ⁠<em>⁠ tags, wraps literal parentheses around it, and prepends a line break tag.

metro |>
  dplyr::select(name, caption, lines) |>
  dplyr::slice(110:120) |>
  gt() |>
  cols_merge(
    columns = c(name, caption),
    pattern = "{1}<< ({2})>>"
  ) |>
  text_replace(
    locations = cells_body(columns = name),
    pattern = "\\((.*?)\\)",
    replacement = "<br>(<em>\\1</em>)"
  )

Function ID

4-1

Function Introduced

v0.9.0 (Mar 31, 2023)

See Also

Other text transforming functions: text_case_match(), text_case_when(), text_transform()

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