The cols_merge_range() function is a specialized variant of the cols_merge() function. It operates by taking a two columns that constitute a range of values (col_begin and col_end) and merges them into a single column. What results is a column containing both values separated by a long dash (e.g., 12.0 — 20.0). The column specified in col_end is dropped from the output table.

cols_merge_range(data, col_begin, col_end, sep = "--", autohide = TRUE)



A table object that is created using the gt() function.


A column that contains values for the start of the range.


A column that contains values for the end of the range.


The separator text that indicates the values are ranged.


An option to automatically hide the column specified as col_end. Any columns with their state changed to hidden will behave the same as before, they just won't be displayed in the finalized table.


An object of class gt_tbl.


This function could be somewhat replicated using cols_merge(), however, cols_merge_range() employs the following specialized operations for NA handling:

  1. NAs in col_begin result in missing values for the merged column (e.g., NA + 20.0 = NA)

  2. NAs in col_end (but not col_begin) result in a display of only the col_begin values only for the merged column (e.g., 12.0 + NA = 12.0)

  3. NAs both in col_begin and col_end result in missing values for the merged column (e.g., NA + NA = NA)

Any resulting NA values in the col_begin column following the merge operation can be easily formatted using the fmt_missing() function.

This function is part of a set of three column-merging functions. The other two are the general cols_merge() function and the specialized cols_merge_uncert() function. These functions operate similarly, where the non-target columns can be optionally hidden from the output table through the hide_columns or autohide options.


Function ID


See also


# Use `gtcars` to create a gt table, # keeping only the `model`, `mpg_c`, # and `mpg_h` columns; merge the mpg # columns together as a single range # column (which is labeled as MPG, # in italics) tab_1 <- gtcars %>% dplyr::select(model, starts_with("mpg")) %>% dplyr::slice(1:8) %>% gt() %>% cols_merge_range( col_begin = vars(mpg_c), col_end = vars(mpg_h) ) %>% cols_label( mpg_c = md("*MPG*") )