gt-tab_header – The gt package

The `tab_header()` function

Let’s use a small portion of the gtcars dataset to create a gt table. A header part can be added to the table with the tab_header() function. We’ll add a title and the optional subtitle as well. With md(), we can make sure the Markdown formatting is interpreted and transformed.

gtcars |>
  dplyr::select(mfr, model, msrp) |>
  dplyr::slice(1:5) |>
  gt() |>
  tab_header(
    title = md("Data listing from **gtcars**"),
    subtitle = md("`gtcars` is an R dataset")
  )

mfr	model	msrp
Data listing from gtcars
`gtcars` is an R dataset
Ford	GT	447000
Ferrari	458 Speciale	291744
Ferrari	458 Spider	263553
Ferrari	458 Italia	233509
Ferrari	488 GTB	245400

If the table is intended solely as an HTML table, you could introduce your own HTML elements into the header. You can even use the htmltools package to help arrange and generate the HTML. Here’s an example of that, where two <div> elements are placed in a htmltools::tagList().

gtcars |>
  dplyr::select(mfr, model, msrp) |>
  dplyr::slice(1:5) |>
  gt() |>
  tab_header(
    title =
      htmltools::tagList(
        htmltools::tags$div(
          htmltools::HTML(
            web_image("https://www.r-project.org/logo/Rlogo.png")
          ),
          style = htmltools::css(`text-align` = "center")
        ),
        htmltools::tags$div(
          "Data listing from ", htmltools::tags$strong("gtcars")
        )
      )
  )

mfr	model	msrp
Data listing from gtcars
Ford	GT	447000
Ferrari	458 Speciale	291744
Ferrari	458 Spider	263553
Ferrari	458 Italia	233509
Ferrari	488 GTB	245400

If using HTML but doing something far simpler, we can wrap our title or subtitle inside html() to declare that the text provided is HTML.

gtcars |>
  dplyr::select(mfr, model, msrp) |>
  dplyr::slice(1:5) |>
  gt() |>
  tab_header(
    title = html("Data listing from <strong>gtcars</strong>"),
    subtitle = html("From <span style='color:red;'>gtcars</span>")
  )

mfr	model	msrp
Data listing from gtcars
From gtcars
Ford	GT	447000
Ferrari	458 Speciale	291744
Ferrari	458 Spider	263553
Ferrari	458 Italia	233509
Ferrari	488 GTB	245400

Sometimes, aligning the heading elements to the left can improve the presentation of a table. Here, we use the nuclides dataset to generate a display of natural abundance values for several stable isotopes. opt_align_table_header() is used with align = "left" to make it so the title and subtitle are left aligned in the header area.

nuclides |>
  dplyr::filter(!is.na(abundance)) |>
  dplyr::filter(abundance != 1) |>
  dplyr::filter(z >= 1 & z <= 8) |>
  dplyr::mutate(element = paste0(element, ", **z = ", z, "**")) |>
  dplyr::mutate(nuclide = gsub("[0-9]+$", "", nuclide)) |>
  dplyr::select(nuclide, element, atomic_mass, abundance, abundance_uncert) |>
  gt(
    rowname_col = "nuclide",
    groupname_col = "element",
    process_md = TRUE
  ) |>
  tab_header(
    title = "Natural Abundance Values",
    subtitle = md("For elements having atomic numbers from `1` to `8`.")
  ) |>
  tab_stubhead(label = "Isotope") |>
  tab_stub_indent(
    rows = everything(),
    indent = 1
  ) |>
  fmt_chem(columns = stub()) |>
  fmt_number(
    columns = atomic_mass,
    decimals = 4,
    scale_by = 1 / 1e6
  ) |>
  fmt_percent(
    columns = contains("abundance"),
    decimals = 4
  ) |>
  cols_merge_uncert(
    col_val = abundance,
    col_uncert = abundance_uncert
  ) |>
  cols_label_with(fn = function(x) tools::toTitleCase(gsub("_", " ", x))) |>
  cols_width(
    stub() ~ px(70),
    atomic_mass ~ px(120),
    abundance ~ px(200)
  ) |>
  opt_align_table_header(align = "left") |>
  opt_vertical_padding(scale = 0.5)

Isotope	Atomic Mass	Abundance
Natural Abundance Values
For elements having atomic numbers from `1` to `8`.
H, z = 1
1 1H	1.0078	99.9855% ± 0.0078%
2 1H	2.0141	0.0145% ± 0.0078%
He, z = 2
3 2He	3.0160	0.0002% ± 0.0002%
4 2He	4.0026	99.9998% ± 0.0002%
Li, z = 3
6 3Li	6.0151	4.8500% ± 1.7100%
7 3Li	7.0160	95.1500% ± 1.7100%
B, z = 5
10 5B	10.0129	19.6500% ± 0.4400%
11 5B	11.0093	80.3500% ± 0.4400%
C, z = 6
12 6C	12.0000	98.9400% ± 0.0600%
13 6C	13.0034	1.0600% ± 0.0600%
N, z = 7
14 7N	14.0031	99.6205% ± 0.0247%
15 7N	15.0001	0.3795% ± 0.0247%
O, z = 8
16 8O	15.9949	99.7570% ± 0.0110%
17 8O	16.9991	0.0384% ± 0.0010%
18 8O	17.9992	0.2045% ± 0.0102%

The tab_header() function

The `tab_header()` function