% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/xl_image.R
\name{xl_image}
\alias{xl_image}
\title{Insert an image into a worksheet}
\usage{
xl_image(
  image,
  at = "A1",
  scale = 1,
  offset = NULL,
  position = "move_and_size",
  description = NULL,
  decorative = FALSE,
  url = NULL,
  tip = NULL,
  embed = FALSE,
  format = NULL
)
}
\arguments{
\item{image}{The image, in any of four shapes: a path to a PNG, JPEG, GIF or
BMP; a raw vector holding one of those encoded; a `raster` (or anything
[grDevices::as.raster()] accepts, such as a colour matrix or an RGB/RGBA
array); or a `nativeRaster`.  The last two are what
[graphics::rasterImage()] draws, so anything you can plot can be written.}

\item{at}{The cell the image is anchored to, such as `"B2"`, or a
`list(rows = , cols = )` spec selecting a single cell.}

\item{scale}{Scale factor: one number for both axes, or `c(x, y)`.}

\item{offset}{Offset from the anchor cell's top-left corner in pixels, as
`c(x, y)`.}

\item{position}{How the image behaves when rows and columns change size:
`"move_and_size"` (the default), `"move_dont_size"`,
`"dont_move_dont_size"`, `"move_and_size_after"`, or `"default"` for
Excel's own default.  Ignored when `embed = TRUE`.}

\item{description}{Alt text, for screen readers.  Excel defaults it to the
file name; `""` writes none.}

\item{decorative}{Mark the image as decorative, so screen readers skip it.
Excel does not write a description for a decorative image.}

\item{url}{An optional hyperlink the image links to.}

\item{tip}{An optional mouseover tip for `url`.}

\item{embed}{Place the image inside the cell rather than floating above it.
Requires a version of Excel that supports images in cells.}

\item{format}{An [xl_format] for the cell holding an embedded image.  Only
meaningful with `embed = TRUE`.}
}
\value{
An `xl_image` object.
}
\description{
`xl_image()` places an image on a sheet, either floating over the cells and
anchored to one of them (the default) or, with `embed = TRUE`, inside a cell.
Pass one or a list of them as `xl_sheet(image = )`.

The image may be a file path or a raw vector, which is convenient when a plot
has just been written by a graphics device and never touched the disk.  PNG,
JPEG, GIF and BMP are supported --- the formats Excel reads --- and the
format is detected from the file's own bytes rather than its extension.
}
\section{Floating versus embedded}{

An inserted image floats above the grid: it has a position but occupies no
cell, and `position` decides whether it moves and resizes as rows and columns
change.  An embedded image (`embed = TRUE`) lives *in* a cell and sizes with
it, which is the Excel 365 "place in cell" behaviour.  Excel versions without
that feature show `#VALUE!` in place of an embedded image, so it is worth
choosing deliberately.
}

\section{Caveats inherited from Excel}{

An image's scaling can shift if it crosses a row whose height changed --- for
a taller font or wrapped text --- so set the height explicitly with
[xl_row_spec()] for rows an image spans.  BMP is supported only for backward
compatibility and must be 24-bit true colour; prefer PNG.  SVG is refused,
because Excel stores it converted to PNG anyway.
}

\examples{
logo <- system.file("help", "figures", "logo.png", package = "writexl")
if (nzchar(logo)) {
  xl_image(logo, at = "C2", scale = 0.5)
  xl_image(logo, at = "C2", url = "https://example.com", tip = "Home")
}
}
\seealso{
[xl_sheet]

Other images and charts:
\code{\link[=xl_chart]{xl_chart()}},
\code{\link[=xl_chart_axis]{xl_chart_axis()}},
\code{\link[=xl_chart_error_bars]{xl_chart_error_bars()}},
\code{\link[=xl_chart_labels]{xl_chart_labels()}},
\code{\link[=xl_chart_legend]{xl_chart_legend()}},
\code{\link[=xl_chart_marker]{xl_chart_marker()}},
\code{\link[=xl_chart_series]{xl_chart_series()}},
\code{\link[=xl_chart_table]{xl_chart_table()}},
\code{\link[=xl_chart_trendline]{xl_chart_trendline()}},
\code{\link[=xl_chartsheet]{xl_chartsheet()}}
}
\concept{images and charts}
