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)



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.


an object of class gt_tbl.


This function could be somewhat replicated using cols_merge(), however, cols_merge_range() employs the following specialized semantics 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 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 second column specified is dropped from the output table. For all of the cols_merge*() functions, column removal occurs late in the rendering lifecycle so those secondary columns are still usable as column references (e.g., inside expressions provided to `rows` in the fmt*() functions).


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*") )