cells_title: Location helper for targeting the table title and subtitle

Description

The cells_title() function is used to target the table title or subtitle when applying a footnote with tab_footnote() or adding custom style with tab_style(). The function is expressly used in each of those functions' locations argument. The header location where the title and optionally the subtitle reside is generated by the tab_header() function.

Usage

cells_title(groups = c("title", "subtitle"))

Value

A list object of classes cells_title and location_cells.

Arguments

groups

Specification of groups

mult-kw:[title|subtitle] // default: c("title", "subtitle")

We can either specify "title", "subtitle", or both (the default) in a vector to target the title element, the subtitle element, or both elements.

Overview of location helper functions

Location helper functions can be used to target cells with virtually any function that has a locations argument. Here is a listing of all of the location helper functions, with locations corresponding roughly from top to bottom of a table:

cells_title(): targets the table title or the table subtitle depending on the value given to the groups argument ("title" or "subtitle").
cells_stubhead(): targets the stubhead location, a cell of which is only available when there is a stub; a label in that location can be created by using the tab_stubhead() function.
cells_column_spanners(): targets the spanner column labels with the spanners argument; spanner column labels appear above the column labels.
cells_column_labels(): targets the column labels with its columns argument.
cells_row_groups(): targets the row group labels in any available row groups using the groups argument.
cells_stub(): targets row labels in the table stub using the rows argument.
cells_body(): targets data cells in the table body using intersections of columns and rows.
cells_summary(): targets summary cells in the table body using the groups argument and intersections of columns and rows.
cells_grand_summary(): targets cells of the table's grand summary using intersections of columns and rows
cells_stub_summary(): targets summary row labels in the table stub using the groups and rows arguments.
cells_stub_grand_summary(): targets grand summary row labels in the table stub using the rows argument.
cells_footnotes(): targets all footnotes in the table footer (cannot be used with tab_footnote()).
cells_source_notes(): targets all source notes in the table footer (cannot be used with tab_footnote()).

When using any of the location helper functions with an appropriate function that has a locations argument (e.g., tab_style()), multiple locations can be targeted by enclosing several cells_*() helper functions in a list() (e.g., list(cells_body(), cells_grand_summary())).

Examples

Use a subset of the sp500 dataset to create a small gt table. Add a header with a title, and then add a footnote to the title with tab_footnote() and cells_title() (in locations).

sp500 |>
  dplyr::filter(date >= "2015-01-05" & date <="2015-01-10") |>
  dplyr::select(-c(adj_close, volume, high, low)) |>
  gt() |>
  tab_header(title = "S&P 500") |>
  tab_footnote(
    footnote = "All values in USD.",
    locations = cells_title(groups = "title")
  )

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

Function ID

8-11

Function Introduced

v0.2.0.5 (March 31, 2020)