UI

The UI needed to support file uploads is simple: just add fileInput() to your UI:

ui <- fluidPage(
  fileInput("upload", "Upload a file")
)

Like most other UI components, there are only two required arguments: id and label. The width, buttonLabel, and placeholder arguments allow you to tweak the appearance in other ways. I won’t discuss them here, but you can read more about them in ?fileInput.

Uploading Data

If the user is uploading a dataset, there are two details that you need to be aware of:

• input$upload is initialized to NULL on page load, so you’ll need req(input$file) to make sure your code waits until the first file is uploaded.

• The accept argument allows you to limit the possible inputs. The easiest way is to supply a character vector of file extensions, like accept = ".csv". But the accept argument is only a suggestion to the browser and is not always enforced, so it’s good practice to also validate it (e.g., “Validation”) yourself. The easiest way to get the file extension in R is tools::file_ext(), but just be aware that it removes the leading . from the extension.

Putting all these ideas together gives us the following, where you can upload a .csv or .tsv file and see the first n rows:

ui <- fluidPage(
  fileInput("file", NULL, accept = c(".csv", ".tsv")),
  numericInput("n", "Rows", value = 5, min = 1, step = 1),
  tableOutput("head")
)

server <- function(input, output, session) {
  data <- reactive({
    req(input$file)

    ext <- tools::file_ext(input$file$name)
    switch(ext,
      csv = vroom::vroom(input$file$datapath, delim = ","),
      tsv = vroom::vroom(input$file$datapath, delim = "	"),
      validate("Invalid file; Please upload a .csv or .tsv file")
    )
  })

  output$head <- renderTable({
    head(data(), input$n)
  })
}

See it in action in the live app.

Note that since multiple = FALSE (the default), input$file will be a single-row data frame, and input$file$name and input$file$datapath will be a length-1 character vector.

Basics

Again, the UI is straightforward: use downloadButton(id) or downloadLink(id) to give the user something to click to download a file:

ui <- fluidPage(
  downloadButton("download1"),
  downloadLink("download2")
)

The results are shown in Figure 9-2.

Figure 9-2. A download button and a download link.

You can customize their appearance using the same class and icon arguments as for actionButtons(), as described in “Action Buttons”.

Unlike other outputs, downloadButton() is not paired with a render function. Instead, you use downloadHandler(), which looks something like this:

output$download <- downloadHandler(
  filename = function() {
    paste0(input$dataset, ".csv")
  },
  content = function(file) {
    write.csv(data(), file)
  }
)

downloadHandler() has two arguments, both functions:

filename

A function with no arguments that returns a filename (as a string). The job of this function is to create the name that will be shown to the user in the download dialog box.

content

A function with one argument, file, which is the path to save the file. The job of this function is to save the file in a place that Shiny knows about so it can then send it to the user.

This is an unusual interface, but it allows Shiny to control where the file should be saved (so it can be placed in a secure location) while you still control the contents of that file.

Next we’ll put these pieces together to show how to transfer data files or reports to the user.

Downloading Data

The following app shows off the basics of data download by allowing you to download any dataset in the datasets package as a tab-separated file, as shown in Figure 9-3. I recommend using .tsv (tab-separated values) instead of .csv (comma-separated values) because many European countries use commas to separate the whole and fractional parts of a number (e.g., 1,23 versus 1.23). This means they can’t use commas to separate fields and instead use semicolons in so-called CSV files! You can avoid this complexity by using tab-separated files, which work the same way everywhere:

ui <- fluidPage(
  selectInput("dataset", "Pick a dataset", ls("package:datasets")),
  tableOutput("preview"),
  downloadButton("download", "Download .tsv")
)

server <- function(input, output, session) {
  data <- reactive({
    out <- get(input$dataset, "package:datasets")
    if (!is.data.frame(out)) {
      validate(paste0("'", input$dataset, "' is not a data frame"))
    }
    out
  })

  output$preview <- renderTable({
    head(data())
  })

  output$download <- downloadHandler(
    filename = function() {
      paste0(input$dataset, ".tsv")
    },
    content = function(file) {
      vroom::vroom_write(data(), file)
    }
  )
}

Figure 9-3. This richer app allows you to select a built-in dataset and preview it before downloading. See live at https://hadley.shinyapps.io/ms-download-data.

Note the use of validate() to only allow the user to download datasets that are data frames. A better approach would be to prefilter the list, but this lets you see another application of validate().

Downloading Reports

As well as downloading data, you may want the users of your app to download a report that summarizes the result of interactive exploration in the Shiny app. This is quite a lot of work, because you also need to display the same information in a different format, but it is very useful for high-stakes apps.

One powerful way to generate such a report is with a parameterized RMarkdown document. A parameterized RMarkdown file has a params field in the YAML metadata:

title: My Document
output: html_document
params:
  year: 2018
  region: Europe
  printcode: TRUE
  data: file.csv

Inside the document, you can refer to these values using elements of the params list (e.g., params$year, params$region). The values in the YAML metadata are defaults; you’ll generally override them by providing the params argument in a call to rmarkdown::render(). This makes it easy to generate many different reports from the same .Rmd.

Here’s a simple example adapted from “Generating downloadable reports”, which describes this technique in more detail. The key idea is to call rmarkdown::render() from the content argument of downloadHandler():

ui <- fluidPage(
  sliderInput("n", "Number of points", 1, 100, 50),
  downloadButton("report", "Generate report")
)

server <- function(input, output, session) {
  output$report <- downloadHandler(
    filename = "report.html",
    content = function(file) {
      params <- list(n = input$n)

      id <- showNotification(
        "Rendering report...",
        duration = NULL,
        closeButton = FALSE
      )
      on.exit(removeNotification(id), add = TRUE)

      rmarkdown::render("report.Rmd",
        output_file = file,
        params = params,
        envir = new.env(parent = globalenv())
      )
    }
  )
}

If you want to produce other output formats, just change the output format in the .Rmd, and make sure to update the extension (e.g., to .pdf). See it in action in the live app. It’ll generally take at least a few seconds to render an .Rmd, so this is a good place to use a notification from “Notifications”.

There are a couple of other tricks worth knowing about:

• RMarkdown works in the current working directory, which will fail in many deployment scenarios (e.g., on shinyapps.io). You can work around this by copying the report to a temporary directory when your app starts (i.e., outside of the server function):

  report_path <- tempfile(fileext = ".Rmd")
  file.copy("report.Rmd", report_path, overwrite = TRUE)

  Then replace "report.Rmd" with report_path in the call to rmarkdown::render():

  rmarkdown::render(report_path,
    output_file = file,
    params = params,
    envir = new.env(parent = globalenv())
  )

• By default, RMarkdown will render the report in the current process, which means that it will inherit many settings from the Shiny app (like loaded packages, options, etc.). For greater robustness, I recommend running render() in a separate R session using the callr package:

  render_report <- function(input, output, params) {
    rmarkdown::render(input,
      output_file = output,
      params = params,
      envir = new.env(parent = globalenv())
    )
  }
  
  server <- function(input, output) {
    output$report <- downloadHandler(
      filename = "report.html",
      content = function(file) {
        params <- list(n = input$slider)
        callr::r(
          render_report,
          list(input = report_path, output = file, params = params)
        )
      }
    )
  }

You can see all these pieces put together in rmarkdown-report/, found inside the Mastering Shiny GitHub repo.

The shinymeta package solves a related problem: sometimes you need to be able to turn the current state of a Shiny app into a reproducible report that can be rerun in the future. Joe Cheng’s useR! 2019 keynote “Shiny’s Holy Grail: Interactivity with Reproducibility” offers more information.