floating_external_img: Floating external image

In officer: Manipulation of Microsoft Word and PowerPoint Documents

Floating external image

Description

Wraps an image in an object that can be embedded as a floating image in a 'Word' document. Unlike external_img(), which creates inline images, this function creates floating images that can be positioned anywhere on the page and allow text wrapping around them.

Usage

floating_external_img(
  src,
  width = 0.5,
  height = 0.2,
  pos_x = 0,
  pos_y = 0,
  pos_h_from = "margin",
  pos_v_from = "margin",
  wrap_type = "square",
  wrap_side = "bothSides",
  wrap_dist_top = 0,
  wrap_dist_bottom = 0,
  wrap_dist_left = 0.125,
  wrap_dist_right = 0.125,
  unit = "in",
  guess_size = FALSE,
  alt = ""
)

Arguments

src	image file path
width, height	size of the image file. It can be ignored if parameter guess_size=TRUE, see parameter guess_size.
pos_x, pos_y	horizontal and vertical position of the image relative to the anchor point
pos_h_from	horizontal positioning reference point, one of "margin", "page", "column", "character"
pos_v_from	vertical positioning reference point, one of "margin", "page", "paragraph", "line"
wrap_type	text wrapping type, one of "square", "topAndBottom", "through", "tight", "none"
wrap_side	which side text wraps around, one of "bothSides", "left", "right", "largest"
wrap_dist_top, wrap_dist_bottom, wrap_dist_left, wrap_dist_right	distance between image and text (in inches)
unit	unit for width, height, pos_x and pos_y, one of "in", "cm", "mm".
guess_size	If package 'magick' is installed, this option can be used (set it to TRUE). The images will be read and width and height will be guessed.
alt	alternative text for images

usage

You can use this function in conjunction with fpar to create paragraphs consisting of differently formatted text parts. You can also use this function as an r chunk in an R Markdown document made with package officedown.

See Also

external_img, body_add, fpar, rtf_doc, rtf_add

Other run functions for reporting: external_img(), ftext(), hyperlink_ftext(), run_autonum(), run_bookmark(), run_columnbreak(), run_comment(), run_footnote(), run_footnoteref(), run_linebreak(), run_pagebreak(), run_reference(), run_tab(), run_word_field(), run_wordtext()

Examples

library(officer)
srcfile <- file.path(R.home("doc"), "html", "logo.jpg")
floatimg <- floating_external_img(
  src = srcfile, height = 1.06 / 2, width = 1.39 / 2,
  pos_x = 0, pos_y = 0,
  pos_h_from = "margin", pos_v_from = "margin"
)

text <- paste0(
  " is a floating image in a ",
  paste0(rep("very ", 30), collapse = ""),
  " long text!"
)

# docx example ----
x <- read_docx()
fp_t <- fp_text(font.size = 20, color = "red")
an_fpar <- fpar(floatimg, ftext(text, fp_t))
x <- body_add_fpar(x, an_fpar)
print(x, target = tempfile(fileext = ".docx"))

# rtf example ----
rtf_doc <- rtf_doc()
rtf_doc <- rtf_add(rtf_doc, an_fpar)
print(rtf_doc, target = tempfile(fileext = ".rtf"))

officer documentation built on Dec. 4, 2025, 9:08 a.m.