cells_stub: Location helper for targeting cells in the table stub

Description

cells_stub() is used to target the table's stub cells and it is useful when applying a footnote with tab_footnote() or adding a custom style with tab_style(). The function is expressly used in each of those functions' locations argument. Here are several ways that a stub location might be available in a gt table: (1) through specification of a rowname_col in gt(), (2) by introducing a data frame with row names to gt() with rownames_to_stub = TRUE, or (3) by using summary_rows() or grand_summary_rows() with neither of the previous two conditions being true.

Usage

cells_stub(rows = everything(), columns = NULL)

Value

A list object with the classes cells_stub and location_cells.

Arguments

rows

Rows to target

<row-targeting expression> // default: everything()

The rows to which targeting operations are constrained. The default everything() results in all rows in the stub being targeted. Multiple targeting methods are supported:

Numeric indices: A vector of row indices within c() (e.g., c(1, 3, 5)).

Content-based targeting: A vector of content values within c() that match values in any stub column (e.g., c("Ford", "BMW") to target all rows containing those manufacturer names). This is particularly useful for multi-column stubs where you want to target based on content rather than calculating row indices.

Select helpers: Use functions like starts_with(), ends_with(), contains(), matches(), num_range(), and everything().

Expressions: Filter expressions to target specific rows (e.g., [colname_1] > 100 & [colname_2] < 50).

When using content-based targeting with multi-column stubs, the function will search all stub columns for matching values unless specific columns are provided to constrain the search.

columns

Stub columns to target

<column-targeting expression> // default: NULL (optional)

The stub columns to which targeting operations are constrained. By default (NULL), all stub columns are targeted for backward compatibility. For tables with multi-column stubs (created with gt(rowname_col = c(...)) or when row_group_as_column = TRUE), you can target specific columns by providing a vector of column names within c(), a vector of column indices, or a select helper function. When columns is specified, only the intersection of the specified columns and rows will be targeted. For single-column stubs, this argument can be omitted for traditional behavior.

Examples

Let's create a gt table using a transformed version of the sza dataset. We'll color all of the month values in the table stub with tab_style(), using cells_stub() in locations.

sza |>
  dplyr::filter(latitude == 20 & tst <= "1000") |>
  dplyr::select(-latitude) |>
  dplyr::filter(!is.na(sza)) |>
  tidyr::pivot_wider(
    names_from = "tst",
    values_from = sza,
    names_sort = TRUE
  ) |>
  gt(rowname_col = "month") |>
  sub_missing(missing_text = "") |>
  tab_style(
    style = list(
      cell_fill(color = "darkblue"),
      cell_text(color = "white")
      ),
    locations = cells_stub()
  )

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

For multi-column stubs, you can target specific columns. Here's an example with a table that has multiple stub columns:

# Create a table with multi-column stub
dplyr::tibble(
  country = rep(c("USA", "Canada"), each = 3),
  region = rep(c("North", "South", "West"), 2),
  pop_2020 = c(5000, 3000, 2000, 4000, 3500, 1500),
  pop_2021 = c(5100, 3100, 2100, 4100, 3600, 1600)
) |>
  gt(rowname_col = c("country", "region")) |>
  tab_style(
    style = cell_fill(color = "lightblue"),
    locations = cells_stub(columns = "country", rows = 1:2)
  ) |>
  tab_style(
    style = cell_text(weight = "bold"),
    locations = cells_stub(columns = "region", rows = c(1, 3, 5))
  )

You can also use content-based targeting to target rows by their actual values rather than calculating row indices:

# Content-based targeting example
gtcars |>
  dplyr::select(mfr, model, year, hp, msrp) |>
  dplyr::slice(1:8) |>
  gt(rowname_col = c("mfr", "model")) |>
  tab_style(
    style = cell_fill(color = "lightcoral"),
    locations = cells_stub(rows = "Ford")  # Targets all Ford rows
  ) |>
  tab_style(
    style = cell_text(weight = "bold"),
    locations = cells_stub(rows = c("BMW", "Audi"), columns = "mfr")
  )

Function ID

8-17

Function Introduced

v0.2.0.5 (March 31, 2020)