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
andindent
)the cell borders (
cell_borders()
)
Arguments
- data
The gt table data object
obj:<gt_tbl>
--- requiredThis is the gt table object that is commonly created through use of the
gt()
function.- style
Style declarations
<style expressions>
--- requiredThe styles to use for the cells at the targeted
locations
. Thecell_text()
,cell_fill()
, andcell_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 alist()
. Custom CSS declarations can be used for HTML output by including acss()
-based statement as a list item.- locations
Locations to target
<locations expressions>
--- requiredThe 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()
, andcells_source_notes()
. Additionally, we can enclose severalcells_*()
calls within alist()
if we wish to apply styling to different types of locations (e.g., body cells, row group labels, the table title, etc.).
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
)
)
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)
)
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)
)
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())
)
See also
cell_text()
, cell_fill()
, and cell_borders()
as helpers for
defining custom styles and cells_body()
as one of many useful helper
functions for targeting the locations to be styled.
Other part creation/modification functions:
tab_caption()
,
tab_footnote()
,
tab_header()
,
tab_info()
,
tab_options()
,
tab_row_group()
,
tab_source_note()
,
tab_spanner_delim()
,
tab_spanner()
,
tab_stub_indent()
,
tab_stubhead()
,
tab_style_body()