% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/xl_merge.R
\name{xl_merge}
\alias{xl_merge}
\title{Merge a range of cells}
\usage{
xl_merge(range, value = NULL, format = NULL)
}
\arguments{
\item{range}{The cells to merge: an Excel range string such as `"A1:C1"`, or
a `list(rows = , cols = )` spec.  It must cover more than one cell ---
Excel has no single-cell merge.}

\item{value}{The value shown in the merged cell: a string, or anything with
an [as.character()] method such as an [xl_rich_string()].  `NULL` leaves
the cell empty.}

\item{format}{An optional [xl_format] applied to the whole merged range.
Merged cells usually want `xl_align(horizontal = "center")`.}
}
\value{
An `xl_merge` object.
}
\description{
`xl_merge()` merges a rectangle of cells into one, as Excel's "Merge and
Centre" does.  Pass one or a list of them as `xl_sheet(merge = )`.

A merged range holds a single value, so `xl_merge()` carries its own `value`
rather than taking it from the data frame.  Merging over cells the data frame
filled keeps only the merged value, exactly as merging in Excel discards
everything but the top-left value.
}
\examples{
xl_merge("A1:C1", "Quarterly results",
         format = xl_align(horizontal = "center") + xl_font(bold = TRUE))

df <- data.frame(a = 1:3, b = 4:6)
sheet <- xl_sheet(df, merge = xl_merge("A5:B5", "Total",
                                       format = xl_font(bold = TRUE)))
tmp <- write_xlsx(list(Data = sheet))
}
\seealso{
[xl_sheet], [xl_format]

Other worksheet features:
\code{\link{xl_conditional}},
\code{\link[=xl_filter]{xl_filter()}},
\code{\link[=xl_filter_keep]{xl_filter_keep()}},
\code{\link[=xl_table]{xl_table()}},
\code{\link[=xl_table_column]{xl_table_column()}},
\code{\link[=xl_validation]{xl_validation()}}
}
\concept{worksheet features}
