Add custom styles to one or more cells

With the tab_style() function we can target specific cells and apply styles to them. This is best done in conjunction with the helper functions cell_text(), cell_fill(), and cell_borders(). At present this function is focused on the application of styles for HTML output only (as such, other output formats will ignore all tab_style() calls). Using the aforementioned helper functions, here are some of the styles we can apply:

the background color of the cell (cell_fill(): color)
the cell's text color, font, and size (cell_text(): color, font, size)
the text style (cell_text(): style), enabling the use of italics or oblique text.
the text weight (cell_text(): weight), allowing the use of thin to bold text (the degree of choice is greater with variable fonts)
the alignment and indentation of text (cell_text(): align and indent)
the cell borders (cell_borders())

Usage

tab_style(data, style, locations)

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.

style

Style declarations

<style expressions> --- required

The styles to use for the cells at the targeted locations. The cell_text(), cell_fill(), and cell_borders() helper functions can be used here to more easily generate valid styles. If using more than one helper function to define styles, all calls must be enclosed in a list(). Custom CSS declarations can be used for HTML output by including a css()-based statement as a list item.

locations

Locations to target

<locations expressions> --- required

The cell or set of cells to be associated with the style. Supplying any of the cells_*() helper functions is a useful way to target the location cells that are associated with the styling. These helper functions are: cells_title(), cells_stubhead(), cells_column_spanners(), cells_column_labels(), cells_row_groups(), cells_stub(), cells_body(), cells_summary(), cells_grand_summary(), cells_stub_summary(), cells_stub_grand_summary(), cells_footnotes(), and cells_source_notes(). Additionally, we can enclose several cells_*() calls within a list() if we wish to apply styling to different types of locations (e.g., body cells, row group labels, the table title, etc.).

Value

An object of class gt_tbl.

Examples

Let's use the exibble dataset to create a simple, two-column gt table (keeping only the num and currency columns). With the tab_style() function (called twice), we'll selectively add style to the values formatted by fmt_number(). In the style argument of each tab_style() call, we can define multiple types of styling with the cell_fill() and cell_text() helper functions (enclosed in a list). The cells to be targeted for styling require the use of helper functions like cells_body(), which is used here with different columns and rows being targeted.

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

This image of a table was generated from the first code example in the `tab_style()` help file.

With a subset of the sp500 dataset, we'll create a different gt table. Here, we'll color the background of entire rows of body cells and do so on the basis of value expressions involving the open and close columns.

sp500 |>
  dplyr::filter(
    date >= "2015-12-01" &
    date <= "2015-12-15"
  ) |>
  dplyr::select(-c(adj_close, volume)) |>
  gt() |>
  tab_style(
    style = cell_fill(color = "lightgreen"),
    locations = cells_body(rows = close > open)
  ) |>
  tab_style(
    style = list(
      cell_fill(color = "red"),
      cell_text(color = "white")
      ),
    locations = cells_body(rows = open > close)
  )

This image of a table was generated from the second code example in the `tab_style()` help file.

With another two-column table based on the exibble dataset, let's create a gt table. First, we'll replace missing values with the sub_missing() function. Next, we'll add styling to the char column. This styling will be HTML-specific and it will involve (all within a list): (1) a cell_fill() call (to set a "lightcyan" background), and (2) a string containing a CSS style declaration ("font-variant: small-caps;").

exibble |>
  dplyr::select(char, fctr) |>
  gt() |>
  sub_missing() |>
  tab_style(
    style = list(
      cell_fill(color = "lightcyan"),
      "font-variant: small-caps;"
    ),
    locations = cells_body(columns = char)
  )

This image of a table was generated from the third code example in the `tab_style()` help file.

In the following table based on the towny dataset, we'll use a larger number of tab_style() calls with the aim of styling each location available in the table. Over six separate uses of tab_style(), different body cells are styled with background colors, the header and the footer also receive background color fills, borders are applied to a column of body cells and also to the column labels, and, the row labels in the stub receive a custom text treatment.

towny |>
  dplyr::filter(csd_type == "city") |>
  dplyr::arrange(desc(population_2021)) |>
  dplyr::select(
    name, land_area_km2, density_2016, density_2021,
    population_2016, population_2021
  ) |>
  dplyr::slice_head(n = 5) |>
  gt(rowname_col = "name") |>
  tab_header(
    title = md(paste("Largest Five", fontawesome::fa("city") , "in `towny`")),
    subtitle = "Changes in vital numbers from 2016 to 2021."
  ) |>
  fmt_number(
    columns = starts_with("population"),
    n_sigfig = 3,
    suffixing = TRUE
  ) |>
  fmt_integer(columns = starts_with("density")) |>
  fmt_number(columns = land_area_km2, decimals = 1) |>
  cols_merge(
    columns = starts_with("density"),
    pattern = paste("{1}", fontawesome::fa("arrow-right"), "{2}")
  ) |>
  cols_merge(
    columns = starts_with("population"),
    pattern = paste("{1}", fontawesome::fa("arrow-right"), "{2}")
  ) |>
  cols_label(
    land_area_km2 = md("Area, km^2^"),
    starts_with("density") ~ md("Density, ppl/km^2^"),
    starts_with("population") ~ "Population"
  ) |>
  cols_align(align = "center", columns = -name) |>
  cols_width(
    stub() ~ px(125),
    everything() ~ px(150)
  ) |>
  tab_footnote(
    footnote = "Data was used from their respective census-year publications.",
    locations = cells_title(groups = "subtitle")
  ) |>
  tab_source_note(source_note = md(
    "All figures are compiled in the `towny` dataset (in the **gt** package)."
  )) |>
  opt_footnote_marks(marks = "letters") |>
  tab_style(
    style = list(
      cell_fill(color = "gray95"),
      cell_borders(sides = c("l", "r"), color = "gray50", weight = px(3))
    ),
    locations = cells_body(columns = land_area_km2)
  ) |>
  tab_style(
    style = cell_fill(color = "lightblue" |> adjust_luminance(steps = 2)),
    locations = cells_body(columns = -land_area_km2)
  ) |>
  tab_style(
    style = list(cell_fill(color = "gray35"), cell_text(color = "white")),
    locations = list(cells_footnotes(), cells_source_notes())
  ) |>
  tab_style(
    style = cell_fill(color = "gray98"),
    locations = cells_title()
  ) |>
  tab_style(
    style = cell_text(
      size = "smaller",
      weight = "bold",
      transform = "uppercase"
    ),
    locations = cells_stub()
  ) |>
  tab_style(
    style = cell_borders(
      sides = c("t", "b"),
      color = "powderblue",
      weight = px(3)
    ),
    locations = list(cells_column_labels(), cells_stubhead())
  )

This image of a table was generated from the fourth code example in the `tab_style()` help file.

Function ID

2-10

Function Introduced

v0.2.0.5 (March 31, 2020)