sumExtras (version 1.0.0)

add_group_colors: Add background colors to group headers with automatic gt conversion

Description

Convenience function that adds background colors to variable group headers and converts the table to gt. This is a terminal operation that combines get_group_rows(), gtsummary::as_gt(), and gt::tab_style() into a single pipeable function.

For text formatting (bold/italic), use add_group_styling() before calling this function.

Usage

add_group_colors(tbl, color = "#E8E8E8")

Value

A gt table object with colored group headers. Note: This is a terminal operation that converts to gt. You cannot pipe to additional gtsummary functions after calling this function.

Arguments

tbl

A gtsummary table object with variable group headers created by gtsummary::add_variable_group_header()

color

Background color(s) for group headers. Default "#E8E8E8" (light gray). Accepts a single color (applied to all groups) or a vector of colors (one per group). Can be any valid CSS color (hex code, color name, rgb(), etc.).

Details

This function:

1. Identifies group header rows with get_group_rows()

2. Converts the table to gt with gtsummary::as_gt()

3. Applies background color using gt::tab_style()

Since this function converts to gt, it should be used as the final styling step in your pipeline. Apply all gtsummary functions (like modify_caption(), modify_footnote(), etc.) and text formatting with add_group_styling() before calling add_group_colors().

See Also

• add_group_styling() for text formatting only (stays gtsummary)

• get_group_rows() for identifying group header rows

• gtsummary::add_variable_group_header() for creating variable groups

• gt::tab_style() for additional gt-specific styling

Examples

# \donttest{
# Basic usage - text formatting then color
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt) |>
  extras() |>
  gtsummary::add_variable_group_header(
    header = "Patient Characteristics",
    variables = age:stage
  ) |>
  add_group_styling() |>
  add_group_colors()

# Custom color - light blue
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt) |>
  extras() |>
  gtsummary::add_variable_group_header(
    header = "Baseline Characteristics",
    variables = age:marker
  ) |>
  add_group_styling() |>
  add_group_colors(color = "#E3F2FD")

# Bold only formatting with custom color
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt) |>
  extras() |>
  gtsummary::add_variable_group_header(
    header = "Clinical Measures",
    variables = marker:stage
  ) |>
  add_group_styling(format = "bold") |>
  add_group_colors(color = "#FFF9E6")

# Multiple group headers with same color
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt) |>
  extras() |>
  gtsummary::add_variable_group_header(
    header = "Demographics",
    variables = age
  ) |>
  gtsummary::add_variable_group_header(
    header = "Disease Measures",
    variables = marker:response
  ) |>
  add_group_styling() |>
  add_group_colors(color = "#E8E8E8")

# Different colors per group
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt) |>
  extras() |>
  gtsummary::add_variable_group_header(
    header = "Demographics",
    variables = age
  ) |>
  gtsummary::add_variable_group_header(
    header = "Disease Measures",
    variables = marker:response
  ) |>
  add_group_styling() |>
  add_group_colors(color = c("#E3F2FD", "#FFF9E6"))
# }