2.1 The minimal table

knitr::kable() converts a data frame to a markdown or HTML table. kableExtra adds a pipe-based API on top to style it.

aq |>
  select(site, income_group, pm25, temp_c) |>
  kable(
    digits  = 1,
    caption = "PM2.5 and temperature by site and income group",
    col.names = c("Site", "Income group", "PM2.5 (µg/m³)", "Temp (°C)")
  ) |>
  kable_styling(
    bootstrap_options = c("striped", "hover", "condensed"),
    full_width = FALSE
  )

2.2 Column specifications

column_spec() controls width, bold, italic, colour, and background for individual columns:

aq |>
  select(site, income_group, canopy_pct, pm25, temp_c) |>
  kable(
    digits    = 1,
    caption   = "Column formatting with column_spec()",
    col.names = c("Site", "Income", "Canopy (%)", "PM2.5", "Temp (°C)")
  ) |>
  kable_styling(full_width = FALSE, font_size = 13) |>
  column_spec(1, bold = TRUE, color = "#1e3a2f") |>
  column_spec(3, width = "8em",
              background = spec_color(aq$canopy_pct,
                                      option = "YlGn", scale_from = c(0,100))) |>
  column_spec(4, color = spec_color(aq$pm25,
                                    option  = "RdYlGn",
                                    direction = -1,
                                    scale_from = c(8, 22)))

2.3 Row-level visual encoding

Rather than relying on row_spec() (which requires xml2 HTML parsing that varies by kableExtra version), the most reliable approach is to encode row-level signals directly in the data before passing to kable() — for example, prepending a symbol to a column’s value:

aq_ranked <- aq |>
  arrange(desc(pm25)) |>
  select(site, income_group, pm25, canopy_pct) |>
  mutate(
    # Encode rank visually in the PM2.5 column itself
    pm25_label = case_when(
      row_number() <= 3 ~ paste0("▲ ", round(pm25, 1)),
      pm25 < 11         ~ paste0("✓ ", round(pm25, 1)),
      TRUE              ~ as.character(round(pm25, 1))
    )
  ) |>
  select(site, income_group, pm25_label, canopy_pct)

aq_ranked |>
  kable(
    digits    = 1,
    caption   = "Sites ranked by PM2.5 — ▲ top 3 highest · ✓ below 11 µg/m³",
    col.names = c("Site", "Income", "PM2.5 (µg/m³)", "Canopy (%)")
  ) |>
  kable_styling(full_width = FALSE,
                bootstrap_options = c("striped", "hover", "condensed"))

2.4 Grouped rows and spanning headers

aq |>
  group_by(income_group, site) |>
  summarise(
    `PM2.5 (µg/m³)` = round(mean(pm25),      1),
    `Canopy (%)`    = round(mean(canopy_pct), 1),
    `Temp (°C)`     = round(mean(temp_c),     1),
    .groups = "drop"
  ) |>
  select(-income_group) |>
  kable(caption = "Summary by income group and urban setting") |>
  kable_styling(full_width = FALSE) |>
  pack_rows("Low-income",    1, 5, bold = TRUE, color = "#c0392b") |>
  pack_rows("Middle-income", 6, 10, bold = TRUE, color = "#e67e22") |>
  pack_rows("High-income",  11, 15, bold = TRUE, color = "#27ae60") |>
  add_header_above(c(" " = 1, "Pollution & Heat Metrics" = 3))

2.5 Table notes

The cleanest cross-version approach is to embed notes directly in the caption argument using paste(). This works regardless of kableExtra version and renders identically in HTML and PDF:

aq |>
  filter(income_group == "Low-income") |>
  select(site, pm25, canopy_pct, temp_c) |>
  kable(
    digits    = 1,
    caption   = paste("Low-income sites (n = 36 per site).",
                      "(a) PM2.5 is the 24-hour mean; EPA NAAQS annual standard = 9 µg/m³.",
                      "(b) Canopy cover estimated from 1-m resolution aerial imagery."),
    col.names = c("Site", "PM2.5 (a)", "Canopy % (b)", "Temp (°C)")
  ) |>
  kable_styling(full_width = FALSE)

2.6 Scrollable tables for long data

# Useful when n > ~20 rows — wraps in a scrollable div
aq |>
  arrange(income_group, desc(pm25)) |>
  kable(
    digits  = 1,
    caption = "All 15 site-income combinations (scrollable)"
  ) |>
  kable_styling(full_width = TRUE) |>
  scroll_box(height = "280px")

3.1 Basic gt table

aq |>
  select(site, income_group, canopy_pct, pm25, temp_c) |>
  gt() |>
  tab_header(
    title    = md("**Urban Heat and Air Quality by Site**"),
    subtitle = "Canopy cover, PM2.5, and mean air temperature"
  ) |>
  cols_label(
    site         = "Site",
    income_group = "Income group",
    canopy_pct   = html("Canopy<br>(%)"),
    pm25         = html("PM2.5<br>(µg/m³)"),
    temp_c       = html("Temp<br>(°C)")
  ) |>
  fmt_number(columns = c(canopy_pct, pm25, temp_c), decimals = 1) |>
  tab_source_note(
    source_note = md("Data collected Spring 2026 · EA030 field campaign")
  )

3.2 Colour scales with data_color()

aq |>
  select(site, income_group, canopy_pct, pm25, temp_c) |>
  gt() |>
  tab_header(title = md("**Colour-coded PM2.5 and Canopy Cover**")) |>
  cols_label(site = "Site", income_group = "Income",
             canopy_pct = "Canopy (%)", pm25 = "PM2.5", temp_c = "Temp (°C)") |>
  fmt_number(columns = c(canopy_pct, pm25, temp_c), decimals = 1) |>
  data_color(
    columns = pm25,
    method  = "numeric",
    palette = c("#27ae60","#f6c90e","#c0392b")
  ) |>
  data_color(
    columns = canopy_pct,
    method  = "numeric",
    palette = c("#fffde7","#1b5e20")
  )

3.3 Spanners (grouped column headers)

aq |>
  select(site, income_group, canopy_pct, pm25, temp_c) |>
  gt() |>
  tab_header(title = md("**Site-Level Environmental Metrics**")) |>
  cols_label(
    site = "Site", income_group = "Income",
    canopy_pct = "Canopy (%)", pm25 = "PM2.5 (µg/m³)", temp_c = "Temp (°C)"
  ) |>
  fmt_number(columns = c(canopy_pct, pm25, temp_c), decimals = 1) |>
  tab_spanner(
    label   = md("🌳 **Vegetation**"),
    columns = canopy_pct
  ) |>
  tab_spanner(
    label   = md("🌡️ **Heat & Air Quality**"),
    columns = c(pm25, temp_c)
  ) |>
  tab_style(
    style     = cell_fill(color = "#e8f5e9"),
    locations = cells_column_spanners()
  )

3.4 Striped rows and bold stub

aq |>
  filter(income_group %in% c("Low-income","High-income")) |>
  select(income_group, site, pm25, canopy_pct) |>
  arrange(income_group, desc(pm25)) |>
  gt(groupname_col = "income_group") |>
  tab_header(title = md("**PM2.5 Ranking: Low vs High-income Sites**")) |>
  cols_label(site = "Site", pm25 = "PM2.5 (µg/m³)", canopy_pct = "Canopy (%)") |>
  fmt_number(columns = c(pm25, canopy_pct), decimals = 1) |>
  opt_row_striping() |>
  tab_style(
    style     = list(cell_text(weight = "bold"),
                     cell_fill(color  = "#1e3a2f"),
                     cell_text(color  = "white")),
    locations = cells_row_groups()
  ) |>
  tab_style(
    style     = cell_text(color = "#c0392b", weight = "bold"),
    locations = cells_body(columns = pm25,
                           rows    = pm25 > 17)
  )

3.5 Summary rows

aq |>
  select(income_group, site, pm25, canopy_pct, temp_c) |>
  gt(groupname_col = "income_group") |>
  tab_header(title = md("**Group Summaries with summary_rows()**")) |>
  cols_label(site = "Site", pm25 = "PM2.5", canopy_pct = "Canopy (%)",
             temp_c = "Temp (°C)") |>
  fmt_number(columns = c(pm25, canopy_pct, temp_c), decimals = 1) |>
  summary_rows(
    groups  = TRUE,
    columns = c(pm25, canopy_pct, temp_c),
    fns     = list(Mean = ~ mean(., na.rm = TRUE)),
    fmt     = ~ fmt_number(., decimals = 1),
    side    = "bottom"
  )

4.1 Basic flextable

aq |>
  select(site, income_group, canopy_pct, pm25, temp_c) |>
  flextable() |>
  set_header_labels(
    site         = "Site",
    income_group = "Income group",
    canopy_pct   = "Canopy (%)",
    pm25         = "PM2.5 (µg/m³)",
    temp_c       = "Temp (°C)"
  ) |>
  colformat_double(digits = 1) |>
  set_caption("Basic flextable output — renders in HTML and Word") |>
  autofit()

4.2 Themes

flextable ships with several pre-built themes that apply a complete visual style in one function call:

aq |>
  select(site, income_group, pm25, canopy_pct, temp_c) |>
  flextable() |>
  set_header_labels(
    site = "Site", income_group = "Income",
    pm25 = "PM2.5", canopy_pct = "Canopy (%)", temp_c = "Temp (°C)"
  ) |>
  colformat_double(digits = 1) |>
  theme_booktabs() |>          # clean academic style
  autofit()

Other themes worth knowing: theme_vanilla(), theme_alafoli(), theme_zebra(), theme_apa().

4.3 Conditional formatting and custom header

ft <- aq |>
  select(site, income_group, pm25, canopy_pct, temp_c) |>
  flextable() |>
  set_header_labels(
    site = "Site", income_group = "Income",
    pm25 = "PM2.5", canopy_pct = "Canopy (%)", temp_c = "Temp (°C)"
  ) |>
  colformat_double(digits = 1) |>
  # Header background
  bg(part = "header", bg = "#1e3a2f") |>
  color(part = "header", color = "white") |>
  bold(part = "header") |>
  # Highlight high PM2.5 rows
  bg(i = ~ pm25 > 17, bg = "#fff3e0") |>
  color(i = ~ pm25 > 17, j = "pm25", color = "#c8832a") |>
  bold(i = ~ pm25 > 17, j = "pm25") |>
  # Shade alternating rows
  bg(i = seq(2, nrow(aq), 2), bg = "#f4f9f6", part = "body") |>
  autofit()

ft

4.4 Merged header cells (spanning)

aq |>
  select(site, income_group, pm25, canopy_pct, temp_c) |>
  flextable() |>
  set_header_labels(
    site = "Site", income_group = "Income",
    pm25 = "PM2.5", canopy_pct = "Canopy", temp_c = "Temp"
  ) |>
  add_header_row(
    values = c("", "", "Heat & Air Quality", "", ""),
    colwidths = c(1, 1, 1, 1, 1)
  ) |>
  # Merge the spanner label across three columns
  merge_at(i = 1, j = 3:5, part = "header") |>
  align(i = 1, j = 3, align = "center", part = "header") |>
  colformat_double(digits = 1) |>
  theme_booktabs() |>
  autofit()

5.1 Basic inline values

5.2 Formatted numbers

Raw numeric output is often too many decimal places for prose. Use round(), format(), or scales::comma() to format inline:

# Best practice: pre-compute complex values in a chunk, then reference
# the named objects inline — easier to debug than long inline expressions
pm25_low  <- aq |> filter(income_group == "Low-income")  |> pull(pm25) |> mean()
pm25_high <- aq |> filter(income_group == "High-income") |> pull(pm25) |> mean()
pm25_diff <- pm25_low - pm25_high
pct_diff  <- pm25_diff / pm25_high * 100

5.3 Inline statistical results

# Pre-compute statistical test results for inline reporting
aov_fit  <- aov(pm25 ~ income_group, data = aq)
aov_tidy <- tidy(aov_fit)
f_val    <- round(aov_tidy$statistic[1], 2)
p_val    <- aov_tidy$p.value[1]
p_fmt    <- ifelse(p_val < 0.001, "< 0.001",
                   paste0("= ", round(p_val, 3)))
df1      <- aov_tidy$df[1]
df2      <- aov_tidy$df[2]

# Correlation
r_val    <- cor(aq$canopy_pct, aq$pm25)

5.4 Inline dates and counts

5.5 The glue approach for cleaner inline strings

# glue() builds strings by interpolating {expressions} — useful for
# constructing longer templated sentences in chunks
library(glue)

income_summary <- aq |>
  group_by(income_group) |>
  summarise(mean_pm25 = round(mean(pm25), 1), .groups = "drop")

sentences <- glue_data(
  income_summary,
  "{income_group} sites: mean PM2.5 = {mean_pm25} µg/m³"
)

sentences

## Low-income sites: mean PM2.5 = 15 µg/m³
## Middle-income sites: mean PM2.5 = 14.1 µg/m³
## High-income sites: mean PM2.5 = 12.8 µg/m³

Using glue() is cleaner than paste() for building sentences from data frames, and the result can be embedded inline with Low-income sites: mean PM2.5 = 15 µg/m³ to pull a specific line.

6.1 broom::tidy() + kableExtra

tidy(lm_fit, conf.int = TRUE) |>
  mutate(
    sig = case_when(
      p.value < 0.001 ~ "***",
      p.value < 0.01  ~ "**",
      p.value < 0.05  ~ "*",
      p.value < 0.1   ~ ".",
      TRUE            ~ ""
    ),
    across(where(is.numeric), ~ round(.x, 4))
  ) |>
  select(term, estimate, std.error, statistic, p.value, conf.low, conf.high, sig) |>
  kable(
    caption   = "OLS regression: PM2.5 ~ canopy + temperature + income group. Significance codes: *** p<.001  ** p<.01  * p<.05  . p<.10",
    col.names = c("Term", "Estimate", "SE", "t", "p-value",
                  "CI low", "CI high", "Sig.")
  ) |>
  kable_styling(full_width = FALSE,
                bootstrap_options = c("striped", "hover", "condensed"))

6.2 Model fit statistics

glance(lm_fit) |>
  select(r.squared, adj.r.squared, sigma, statistic, p.value,
         df, df.residual, nobs, AIC, BIC) |>
  mutate(across(where(is.numeric), ~ round(.x, 4))) |>
  pivot_longer(everything(), names_to = "Statistic", values_to = "Value") |>
  kable(caption = "Model fit statistics from glance()") |>
  kable_styling(full_width = FALSE, font_size = 13) |>
  column_spec(1, bold = TRUE, color = "#1e3a2f")

6.3 Reporting a model result inline

fit_sum  <- summary(lm_fit)
r2       <- round(fit_sum$r.squared,     3)
adj_r2   <- round(fit_sum$adj.r.squared, 3)
f_stat   <- round(fit_sum$fstatistic[1], 2)
f_df1    <- fit_sum$fstatistic[2]
f_df2    <- fit_sum$fstatistic[3]
f_p      <- pf(fit_sum$fstatistic[1], f_df1, f_df2, lower.tail = FALSE)
f_p_fmt  <- ifelse(f_p < 0.001, "< 0.001", paste0("= ", round(f_p, 3)))

canopy_coef <- round(coef(lm_fit)["canopy_pct"], 3)
canopy_p    <- round(tidy(lm_fit)$p.value[tidy(lm_fit)$term == "canopy_pct"], 4)

6.4 gt model table with colour

tidy(lm_fit, conf.int = TRUE) |>
  mutate(sig = case_when(p.value < 0.001 ~ "***", p.value < 0.01 ~ "**",
                         p.value < 0.05  ~ "*",   TRUE ~ "")) |>
  gt() |>
  tab_header(
    title    = md("**Regression Coefficients**"),
    subtitle = "PM2.5 ~ canopy cover + temperature + income group"
  ) |>
  cols_label(
    term      = "Term",       estimate  = "Estimate",
    std.error = "SE",         statistic = "t",
    p.value   = "p-value",   conf.low  = "CI low",
    conf.high = "CI high",   sig       = "Sig."
  ) |>
  fmt_number(columns = c(estimate, std.error, statistic, conf.low, conf.high),
             decimals = 3) |>
  fmt_number(columns = p.value, decimals = 4) |>
  data_color(
    columns = p.value,
    method  = "numeric",
    palette = c("#27ae60","#f6c90e","#e74c3c"),
    reverse = TRUE,
    domain  = c(0, 0.2)
  ) |>
  tab_style(
    style     = cell_text(weight = "bold"),
    locations = cells_body(columns = sig, rows = sig != "")
  ) |>
  tab_footnote(
    footnote  = "*** p<.001  ** p<.01  * p<.05",
    locations = cells_column_labels(columns = sig)
  )

What’s next?

• Functional Programming — use purrr to generate tables for many groups at once
• Data Import — reading the data that feeds your tables
• Visualization — when a plot communicates better than a table