add_group_styling: Apply styling to variable group headers in gtsummary tables

Description

Adds customizable formatting to variable group headers in gtsummary tables. Variable groups are created using gtsummary::add_variable_group_header() to organize variables into sections. This function makes group headers stand out from individual variable labels.

Usage

add_group_styling(tbl, format = c("bold", "italic"), indent_labels = 0L)

Value

A gtsummary table object with specified formatting applied to variable group headers

Arguments

tbl: A gtsummary table object (e.g., from tbl_summary(), tbl_regression())
format: Character vector specifying text formatting. Options include "bold", "italic", or both. Default is c("bold", "italic").
indent_labels: Integer specifying indentation level (in spaces) for variable labels under group headers. Default is 0L (left-aligned). Set to 4L to preserve gtsummary's default group indentation, or use any non-negative integer for custom spacing.

Details

The function targets rows where row_type == 'variable_group' and applies the specified text formatting to the label column.

By default, variable labels are left-aligned (indent_labels = 0L) to distinguish them from categorical levels and statistics. Use indent_labels = 4L to preserve the default gtsummary behavior where grouped variables are indented under their group headers.

Examples

Run this code

# \donttest{
# Default formatting (bold and italic)
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt, include = c(age, marker, grade)) |>
  gtsummary::add_variable_group_header(
    header = "Patient Characteristics",
    variables = age:grade
  ) |>
  add_group_styling()

# Bold only
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt, include = c(age, marker)) |>
  gtsummary::add_variable_group_header(
    header = "Demographics",
    variables = age:marker
  ) |>
  add_group_styling(format = "bold")

# Multiple group headers
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt) |>
  gtsummary::add_variable_group_header(
    header = "Demographics",
    variables = age
  ) |>
  gtsummary::add_variable_group_header(
    header = "Clinical Measures",
    variables = marker:response
  ) |>
  add_group_styling()

# Custom indentation for grouped variables
gtsummary::trial |>
  gtsummary::tbl_summary(by = trt, include = c(age, marker)) |>
  gtsummary::add_variable_group_header(
    header = "Patient Measures",
    variables = age:marker
  ) |>
  add_group_styling(indent_labels = 4L) # gtsummary indentation restored
# }