This is a demo of the function pixfigure(). This is useful for individual images or a set of images but not in a gallery format. The mandatory input required is one or more paths/URLs to image(s).

paths <- c(

Clicking on the thumbnail opens up the full image in a lightbox.



Optionally, captions can be added to the images which are displayed below the images as well as in the lightbox.

pixfigure(paths[1], caption="Night sky over the mountains")


The argument h and w is used to adjust the dimension of the image. This value is a string in any valid css unit.

pixfigure(paths[1], w="400px")
pixfigure(paths[3], h="400px", caption="shark")


The argument fit is used to control css property object-fit. It is set to cover by default.

pixfigure(paths[1], h="600px")

Resize the width of the page to see the effect of fit="cover". The image scales within it’s frame rather than shrink. Explore css property object-fit for more details, for example, on w3schools.


The argument position determines how the image is positioned within the frame. This controls css property object-position.

pixfigure(paths[1], h="400px", w="400px", position="left")
pixfigure(paths[1], h="400px", w="400px", position="right")

Here is a youtube video that discusses fit and position.

Multiple images

Input can also be a vector images. Images are displayed one after the other.

pixfigure(paths, caption=c("Night sky over the mountains", "Walking through dense woodland", "Out in the open seas"), h="200px", w="250px", position="left")

Local images

Local images (not on the internet) can be provided as relative or absolute paths. The images do not show up in the RStudio notebook preview, but they should work in a rendered html document.

    Pixture does not move, copy or embed images. The images must be in their final intended destination. It is left to the user to handle images as assets. Images are not embedded into the html if you use self_contained: true.

Relative path

This example assumes your images are available next to the Rmd/html file in a directory named images and that you copy these assets if the Rmd/html is relocated.

pixfigure("images/pexels-photo-3126574.jpg", h="300px")

Absolute path

Here is another example using sample images from the package. These should work locally, but may not work if the rendered html is relocated.

paths <- list.files(system.file("extdata/images", package="pixture"), full=TRUE)

Shiny app

This is an example of a shiny app using pixfigure().

To try out a demo app, run pixture::runPixfigure(). Use shiny helper functions pixfigureOutput() and renderPixfigure(). The shiny code is given below:

path <- ";;"
captions <- "Palm trees;Night sky;Woodland"

ui <- fluidPage(
    titlePanel("Pixfigure Demo"),
            textAreaInput("path", "Image URLs", value=path, height="200px"),
            checkboxInput("caption_check", "Use captions", value=FALSE),
            textInput("height", label = "Height", value="auto"),
            textInput("width", label = "Width", value="100%"),
            textInput("fit", label = "Object fit", value="cover"),
            textInput("position", label = "Object position", value="center"),
            HTML("Image from <a href=''>Pexels.</a>")

server <- function(input, output) {
    output$caption_ui <- renderUI({
        if(input$caption_check) {
            textInput("caption", "Caption", value=captions)

    output$fig <- pixture::renderPixfigure({
      if(!is.null(input$path)) path <- unlist(strsplit(input$path, ";"))

          cpt <- unlist(strsplit(input$caption, ";"))
          if(length(cpt)!=length(path)) stop("Number of captions do not match number of images.")
          pixture::pixfigure(path, caption=cpt, h = input$height, w = input$width, fit = input$fit, position = input$position)
          pixture::pixfigure(path, h = input$height, w = input$width, fit = input$fit, position = input$position)

shinyApp(ui = ui, server = server)

To use local images in Shiny, the images can be added to the www directory and the paths are relative. For example; an image at app/www/images/image.jpg is referenced in the app as images/image.jpg.