This function takes any two columns and merges them into a single column, using a pattern that specifies how the values in the data cells are combined. We specify the columns to merge together in the col_1 and col_2 arguments and the string-combining pattern is specified in pattern. The column that is retained is that of col_1 whereas the column specified in col_2 is dropped from the output table.

cols_merge(data, col_1, col_2, pattern = "{1} {2}")



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


A retained column that contains values to be merged with those in col_2.


A column that contains values to be merged with those in col_1. This column will be discarded but is still useful as a reference in other gt functions.


A formatting pattern that specifies the arrangement of the col_1 and col_1 values and any string literals. The col_1 column is represented as {1} whereas col_2 is {2}. All other characters are taken to be string literals.


An object of class gt_tbl.


There are two other column-merging functions that offer specialized behavior that is optimized for common table tasks: cols_merge_range() and cols_merge_uncert(). 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 `sp500` to create a gt table; # merge the `open` & `close` columns # together, and, the `low` & `high` # columns (putting an em dash between # both); rename the columns tab_1 <- sp500 %>% dplyr::slice(50:55) %>% dplyr::select(-volume, -adj_close) %>% gt() %>% cols_merge( col_1 = vars(open), col_2 = vars(close), pattern = "{1}&mdash;{2}" ) %>% cols_merge( col_1 = vars(low), col_2 = vars(high), pattern = "{1}&mdash;{2}" ) %>% cols_label( open = "open/close", low = "low/high" )