Reporting progress (functional API)

Reports progress to the user during long-running operations.

withProgress(
  expr,
  min = 0,
  max = 1,
  value = min + (max - min) * 0.1,
  message = NULL,
  detail = NULL,
  style = getShinyOption("progress.style", default = "notification"),
  session = getDefaultReactiveDomain(),
  env = parent.frame(),
  quoted = FALSE
)

setProgress(
  value = NULL,
  message = NULL,
  detail = NULL,
  session = getDefaultReactiveDomain()
)

incProgress(
  amount = 0.1,
  message = NULL,
  detail = NULL,
  session = getDefaultReactiveDomain()
)

Arguments

expr	The work to be done. This expression should contain calls to `setProgress()` or `incProgress()`.
min	The value that represents the starting point of the progress bar. Must be less tham `max`. Default is 0.
max	The value that represents the end of the progress bar. Must be greater than `min`. Default is 1.
value	Single-element numeric vector; the value at which to set the progress bar, relative to `min` and `max`.
message	A single-element character vector; the message to be displayed to the user, or `NULL` to hide the current message (if any).
detail	A single-element character vector; the detail message to be displayed to the user, or `NULL` to hide the current detail message (if any). The detail message will be shown with a de-emphasized appearance relative to `message`.
style	Progress display style. If `"notification"` (the default), the progress indicator will show using Shiny's notification API. If `"old"`, use the same HTML and CSS used in Shiny 0.13.2 and below (this is for backward-compatibility).
session	The Shiny session object, as provided by `shinyServer` to the server function. The default is to automatically find the session by using the current reactive domain.
env	The environment in which `expr` should be evaluated.
quoted	Whether `expr` is a quoted expression (this is not common).
amount	For `incProgress`, the amount to increment the status bar. Default is 0.1.

Value

The result of expr.

Details

This package exposes two distinct programming APIs for working with progress. Using withProgress with incProgress or setProgress provide a simple function-based interface, while the Progress() reference class provides an object-oriented API.

Use withProgress to wrap the scope of your work; doing so will cause a new progress panel to be created, and it will be displayed the first time incProgress or setProgress are called. When withProgress exits, the corresponding progress panel will be removed.

The incProgress function increments the status bar by a specified amount, whereas the setProgress function sets it to a specific value, and can also set the text displayed.

Generally, withProgress/incProgress/setProgress should be sufficient; the exception is if the work to be done is asynchronous (this is not common) or otherwise cannot be encapsulated by a single scope. In that case, you can use the Progress reference class.

As of version 0.14, the progress indicators use Shiny's new notification API. If you want to use the old styling (for example, you may have used customized CSS), you can use style="old" each time you call withProgress(). If you don't want to set the style each time withProgress is called, you can instead call shinyOptions(progress.style="old") just once, inside the server function.

Examples

## Only run examples in interactive R sessions
if (interactive()) {
options(device.ask.default = FALSE)

ui <- fluidPage(
  plotOutput("plot")
)

server <- function(input, output) {
  output$plot <- renderPlot({
    withProgress(message = 'Calculation in progress',
                 detail = 'This may take a while...', value = 0, {
      for (i in 1:15) {
        incProgress(1/15)
        Sys.sleep(0.25)
      }
    })
    plot(cars)
  })
}

shinyApp(ui, server)
}

Arguments

Value

Details

See also

Examples