Type:	Package
Title:	Web Application Framework for R
Version:	1.10.0
Description:	Makes it incredibly easy to build interactive web applications with R. Automatic "reactive" binding between inputs and outputs and extensive prebuilt widgets make it possible to build beautiful, responsive, and powerful applications with minimal effort.
License:	GPL-3 | file LICENSE
Depends:	R (≥ 3.0.2), methods
Imports:	utils, grDevices, httpuv (≥ 1.5.2), mime (≥ 0.3), jsonlite (≥ 0.9.16), xtable, fontawesome (≥ 0.4.0), htmltools (≥ 0.5.4), R6 (≥ 2.0), sourcetools, later (≥ 1.0.0), promises (≥ 1.3.2), tools, crayon, rlang (≥ 0.4.10), fastmap (≥ 1.1.1), withr, commonmark (≥ 1.7), glue (≥ 1.3.2), bslib (≥ 0.6.0), cachem (≥ 1.1.0), lifecycle (≥ 0.2.0)
Suggests:	coro (≥ 1.1.0), datasets, DT, Cairo (≥ 1.5-5), testthat (≥ 3.0.0), knitr (≥ 1.6), markdown, rmarkdown, ggplot2, reactlog (≥ 1.0.0), magrittr, yaml, future, dygraphs, ragg, showtext, sass
URL:	https://shiny.posit.co/, https://github.com/rstudio/shiny
BugReports:	https://github.com/rstudio/shiny/issues
Collate:	'globals.R' 'app-state.R' 'app_template.R' 'bind-cache.R' 'bind-event.R' 'bookmark-state-local.R' 'bookmark-state.R' 'bootstrap-deprecated.R' 'bootstrap-layout.R' 'conditions.R' 'map.R' 'utils.R' 'bootstrap.R' 'busy-indicators-spinners.R' 'busy-indicators.R' 'cache-utils.R' 'deprecated.R' 'devmode.R' 'diagnose.R' 'extended-task.R' 'fileupload.R' 'graph.R' 'reactives.R' 'reactive-domains.R' 'history.R' 'hooks.R' 'html-deps.R' 'image-interact-opts.R' 'image-interact.R' 'imageutils.R' 'input-action.R' 'input-checkbox.R' 'input-checkboxgroup.R' 'input-date.R' 'input-daterange.R' 'input-file.R' 'input-numeric.R' 'input-password.R' 'input-radiobuttons.R' 'input-select.R' 'input-slider.R' 'input-submit.R' 'input-text.R' 'input-textarea.R' 'input-utils.R' 'insert-tab.R' 'insert-ui.R' 'jqueryui.R' 'knitr.R' 'middleware-shiny.R' 'middleware.R' 'timer.R' 'shiny.R' 'mock-session.R' 'modal.R' 'modules.R' 'notifications.R' 'priorityqueue.R' 'progress.R' 'react.R' 'reexports.R' 'render-cached-plot.R' 'render-plot.R' 'render-table.R' 'run-url.R' 'runapp.R' 'serializers.R' 'server-input-handlers.R' 'server-resource-paths.R' 'server.R' 'shiny-options.R' 'shiny-package.R' 'shinyapp.R' 'shinyui.R' 'shinywrappers.R' 'showcase.R' 'snapshot.R' 'staticimports.R' 'tar.R' 'test-export.R' 'test-server.R' 'test.R' 'update-input.R' 'utils-lang.R' 'version_bs_date_picker.R' 'version_ion_range_slider.R' 'version_jquery.R' 'version_jqueryui.R' 'version_selectize.R' 'version_strftime.R' 'viewer.R'
RoxygenNote:	7.3.2
Encoding:	UTF-8
RdMacros:	lifecycle
Config/testthat/edition:	3
Config/Needs/check:	shinytest2
NeedsCompilation:	no
Packaged:	2024-12-13 21:47:15 UTC; cpsievert
Author:	Winston Chang [aut, cre], Joe Cheng [aut], JJ Allaire [aut], Carson Sievert [aut], Barret Schloerke [aut], Yihui Xie [aut], Jeff Allen [aut], Jonathan McPherson [aut], Alan Dipert [aut], Barbara Borges [aut], Posit Software, PBC [cph, fnd], jQuery Foundation [cph] (jQuery library and jQuery UI library), jQuery contributors [ctb, cph] (jQuery library; authors listed in inst/www/shared/jquery-AUTHORS.txt), jQuery UI contributors [ctb, cph] (jQuery UI library; authors listed in inst/www/shared/jqueryui/AUTHORS.txt), Mark Otto [ctb] (Bootstrap library), Jacob Thornton [ctb] (Bootstrap library), Bootstrap contributors [ctb] (Bootstrap library), Twitter, Inc [cph] (Bootstrap library), Prem Nawaz Khan [ctb] (Bootstrap accessibility plugin), Victor Tsaran [ctb] (Bootstrap accessibility plugin), Dennis Lembree [ctb] (Bootstrap accessibility plugin), Srinivasu Chakravarthula [ctb] (Bootstrap accessibility plugin), Cathy O'Connor [ctb] (Bootstrap accessibility plugin), PayPal, Inc [cph] (Bootstrap accessibility plugin), Stefan Petre [ctb, cph] (Bootstrap-datepicker library), Andrew Rowls [ctb, cph] (Bootstrap-datepicker library), Brian Reavis [ctb, cph] (selectize.js library), Salmen Bejaoui [ctb, cph] (selectize-plugin-a11y library), Denis Ineshin [ctb, cph] (ion.rangeSlider library), Sami Samhuri [ctb, cph] (Javascript strftime library), SpryMedia Limited [ctb, cph] (DataTables library), John Fraser [ctb, cph] (showdown.js library), John Gruber [ctb, cph] (showdown.js library), Ivan Sagalaev [ctb, cph] (highlight.js library), R Core Team [ctb, cph] (tar implementation from R)
Maintainer:	Winston Chang <winston@posit.co>
Repository:	CRAN
Date/Publication:	2024-12-14 00:10:02 UTC

Web Application Framework for R

Description

Shiny makes it incredibly easy to build interactive web applications with R. Automatic "reactive" binding between inputs and outputs and extensive prebuilt widgets make it possible to build beautiful, responsive, and powerful applications with minimal effort.

Details

The Shiny tutorial at https://shiny.rstudio.com/tutorial/ explains the framework in depth, walks you through building a simple application, and includes extensive annotated examples.

Author(s)

Maintainer: Winston Chang winston@posit.co (ORCID)

Authors:

• Joe Cheng joe@posit.co

• JJ Allaire jj@posit.co

• Carson Sievert carson@posit.co (ORCID)

• Barret Schloerke barret@posit.co (ORCID)

• Yihui Xie yihui@posit.co

• Jeff Allen

• Jonathan McPherson jonathan@posit.co

• Alan Dipert

• Barbara Borges

Other contributors:

• Posit Software, PBC [copyright holder, funder]

• jQuery Foundation (jQuery library and jQuery UI library) [copyright holder]

• jQuery contributors (jQuery library; authors listed in inst/www/shared/jquery-AUTHORS.txt) [contributor, copyright holder]

• jQuery UI contributors (jQuery UI library; authors listed in inst/www/shared/jqueryui/AUTHORS.txt) [contributor, copyright holder]

• Mark Otto (Bootstrap library) [contributor]

• Jacob Thornton (Bootstrap library) [contributor]

• Bootstrap contributors (Bootstrap library) [contributor]

• Twitter, Inc (Bootstrap library) [copyright holder]

• Prem Nawaz Khan (Bootstrap accessibility plugin) [contributor]

• Victor Tsaran (Bootstrap accessibility plugin) [contributor]

• Dennis Lembree (Bootstrap accessibility plugin) [contributor]

• Srinivasu Chakravarthula (Bootstrap accessibility plugin) [contributor]

• Cathy O'Connor (Bootstrap accessibility plugin) [contributor]

• PayPal, Inc (Bootstrap accessibility plugin) [copyright holder]

• Stefan Petre (Bootstrap-datepicker library) [contributor, copyright holder]

• Andrew Rowls (Bootstrap-datepicker library) [contributor, copyright holder]

• Brian Reavis (selectize.js library) [contributor, copyright holder]

• Salmen Bejaoui (selectize-plugin-a11y library) [contributor, copyright holder]

• Denis Ineshin (ion.rangeSlider library) [contributor, copyright holder]

• Sami Samhuri (Javascript strftime library) [contributor, copyright holder]

• SpryMedia Limited (DataTables library) [contributor, copyright holder]

• John Fraser (showdown.js library) [contributor, copyright holder]

• John Gruber (showdown.js library) [contributor, copyright holder]

• Ivan Sagalaev (highlight.js library) [contributor, copyright holder]

• R Core Team (tar implementation from R) [contributor, copyright holder]

See Also

shiny-options for documentation about global options.

Panel with absolute positioning

Description

Creates a panel whose contents are absolutely positioned.

Usage

absolutePanel(
  ...,
  top = NULL,
  left = NULL,
  right = NULL,
  bottom = NULL,
  width = NULL,
  height = NULL,
  draggable = FALSE,
  fixed = FALSE,
  cursor = c("auto", "move", "default", "inherit")
)

fixedPanel(
  ...,
  top = NULL,
  left = NULL,
  right = NULL,
  bottom = NULL,
  width = NULL,
  height = NULL,
  draggable = FALSE,
  cursor = c("auto", "move", "default", "inherit")
)

Arguments

Details

The absolutePanel function creates a ⁠<div>⁠ tag whose CSS position is set to absolute (or fixed if fixed = TRUE). The way absolute positioning works in HTML is that absolute coordinates are specified relative to its nearest parent element whose position is not set to static (which is the default), and if no such parent is found, then relative to the page borders. If you're not sure what that means, just keep in mind that you may get strange results if you use absolutePanel from inside of certain types of panels.

The fixedPanel function is the same as absolutePanel with fixed = TRUE.

The position (top, left, right, bottom) and size (width, height) parameters are all optional, but you should specify exactly two of top, bottom, and height and exactly two of left, right, and width for predictable results.

Like most other distance parameters in Shiny, the position and size parameters take a number (interpreted as pixels) or a valid CSS size string, such as "100px" (100 pixels) or "25%".

For arcane HTML reasons, to have the panel fill the page or parent you should specify 0 for top, left, right, and bottom rather than the more obvious width = "100%" and height = "100%".

Value

An HTML element or list of elements.

Action button/link

Description

Creates an action button or link whose value is initially zero, and increments by one each time it is pressed.

Usage

actionButton(inputId, label, icon = NULL, width = NULL, disabled = FALSE, ...)

actionLink(inputId, label, icon = NULL, ...)

Arguments

Server value

An integer of class "shinyActionButtonValue". This class differs from ordinary integers in that a value of 0 is considered "falsy". This implies two things:

• Event handlers (e.g., observeEvent(), eventReactive()) won't execute on initial load.

• Input validation (e.g., req(), need()) will fail on initial load.

See Also

observeEvent() and eventReactive()

Other input elements: checkboxGroupInput(), checkboxInput(), dateInput(), dateRangeInput(), fileInput(), numericInput(), passwordInput(), radioButtons(), selectInput(), sliderInput(), submitButton(), textAreaInput(), textInput(), varSelectInput()

Examples

## Only run examples in interactive R sessions
if (interactive()) {

ui <- fluidPage(
  sliderInput("obs", "Number of observations", 0, 1000, 500),
  actionButton("goButton", "Go!", class = "btn-success"),
  plotOutput("distPlot")
)

server <- function(input, output) {
  output$distPlot <- renderPlot({
    # Take a dependency on input$goButton. This will run once initially,
    # because the value changes from NULL to 0.
    input$goButton

    # Use isolate() to avoid dependency on input$obs
    dist <- isolate(rnorm(input$obs))
    hist(dist)
  })
}

shinyApp(ui, server)

}

## Example of adding extra class values
actionButton("largeButton", "Large Primary Button", class = "btn-primary btn-lg")
actionLink("infoLink", "Information Link", class = "btn-info")

Resource Publishing

Description

Add, remove, or list directory of static resources to Shiny's web server, with the given path prefix. Primarily intended for package authors to make supporting JavaScript/CSS files available to their components.

Usage

addResourcePath(prefix, directoryPath)

resourcePaths()

removeResourcePath(prefix)

Arguments

Details

Shiny provides two ways of serving static files (i.e., resources):

1. Static files under the ⁠www/⁠ directory are automatically made available under a request path that begins with /.

2. addResourcePath() makes static files in a directoryPath available under a request path that begins with prefix.

The second approach is primarily intended for package authors to make supporting JavaScript/CSS files available to their components.

Tools for managing static resources published by Shiny's web server:

• addResourcePath() adds a directory of static resources.

• resourcePaths() lists the currently active resource mappings.

• removeResourcePath() removes a directory of static resources.

See Also

singleton()

Examples

addResourcePath('datasets', system.file('data', package='datasets'))
resourcePaths()
removeResourcePath('datasets')
resourcePaths()

# make sure all resources are removed
lapply(names(resourcePaths()), removeResourcePath)

Apply input handlers to raw input values

Description

The purpose of this function is to make it possible for external packages to test Shiny inputs. It takes a named list of raw input values, applies input handlers to those values, and then returns a named list of the processed values.

Usage

applyInputHandlers(inputs, shinysession = getDefaultReactiveDomain())

Arguments

Details

The raw input values should be in a named list. Some values may have names like "x:shiny.date". This function would apply the "shiny.date" input handler to the value, and then rename the result to "x", in the output.

See Also

registerInputHandler

Add caching with reactivity to an object

Description

bindCache() adds caching reactive() expressions and ⁠render*⁠ functions (like renderText(), renderTable(), ...).

Ordinary reactive() expressions automatically cache their most recent value, which helps to avoid redundant computation in downstream reactives. bindCache() will cache all previous values (as long as they fit in the cache) and they can be shared across user sessions. This allows bindCache() to dramatically improve performance when used correctly.

Usage

bindCache(x, ..., cache = "app")

Arguments

Details

bindCache() requires one or more expressions that are used to generate a cache key, which is used to determine if a computation has occurred before and hence can be retrieved from the cache. If you're familiar with the concept of memoizing pure functions (e.g., the memoise package), you can think of the cache key as the input(s) to a pure function. As such, one should take care to make sure the use of bindCache() is pure in the same sense, namely:

1. For a given key, the return value is always the same.

2. Evaluation has no side-effects.

In the example here, the bindCache() key consists of input$x and input$y combined, and the value is input$x * input$y. In this simple example, for any given key, there is only one possible returned value.

r <- reactive({ input$x * input$y }) %>%
  bindCache(input$x, input$y)

The largest performance improvements occur when the cache key is fast to compute and the reactive expression is slow to compute. To see if the value should be computed, a cached reactive evaluates the key, and then serializes and hashes the result. If the resulting hashed key is in the cache, then the cached reactive simply retrieves the previously calculated value and returns it; if not, then the value is computed and the result is stored in the cache before being returned.

To compute the cache key, bindCache() hashes the contents of ..., so it's best to avoid including large objects in a cache key since that can result in slow hashing. It's also best to avoid reference objects like environments and R6 objects, since the serialization of these objects may not capture relevant changes.

If you want to use a large object as part of a cache key, it may make sense to do some sort of reduction on the data that still captures information about whether a value can be retrieved from the cache. For example, if you have a large data set with timestamps, it might make sense to extract the most recent timestamp and return that. Then, instead of hashing the entire data object, the cached reactive only needs to hash the timestamp.

r <- reactive({ compute(bigdata()) } %>%
  bindCache({ extract_most_recent_time(bigdata()) })

For computations that are very slow, it often makes sense to pair bindCache() with bindEvent() so that no computation is performed until the user explicitly requests it (for more, see the Details section of bindEvent()).

Cache keys and reactivity

Because the value expression (from the original reactive()) is cached, it is not necessarily re-executed when someone retrieves a value, and therefore it can't be used to decide what objects to take reactive dependencies on. Instead, the key is used to figure out which objects to take reactive dependencies on. In short, the key expression is reactive, and value expression is no longer reactive.

Here's an example of what not to do: if the key is input$x and the value expression is from reactive({input$x + input$y}), then the resulting cached reactive will only take a reactive dependency on input$x – it won't recompute {input$x + input$y} when just input$y changes. Moreover, the cache won't use input$y as part of the key, and so it could return incorrect values in the future when it retrieves values from the cache. (See the examples below for an example of this.)

A better cache key would be something like ⁠input$x, input$y⁠. This does two things: it ensures that a reactive dependency is taken on both input$x and input$y, and it also makes sure that both values are represented in the cache key.

In general, key should use the same reactive inputs as value, but the computation should be simpler. If there are other (non-reactive) values that are consumed, such as external data sources, they should be used in the key as well. Note that if the key is large, it can make sense to do some sort of reduction on it so that the serialization and hashing of the cache key is not too expensive.

Remember that the key is reactive, so it is not re-executed every single time that someone accesses the cached reactive. It is only re-executed if it has been invalidated by one of the reactives it depends on. For example, suppose we have this cached reactive:

r <- reactive({ input$x * input$y }) %>%
 bindCache(input$x, input$y)

In this case, the key expression is essentially reactive(list(input$x, input$y)) (there's a bit more to it, but that's a good enough approximation). The first time r() is called, it executes the key, then fails to find it in the cache, so it executes the value expression, { input$x + input$y }. If r() is called again, then it does not need to re-execute the key expression, because it has not been invalidated via a change to input$x or input$y; it simply returns the previous value. However, if input$x or input$y changes, then the reactive expression will be invalidated, and the next time that someone calls r(), the key expression will need to be re-executed.

Note that if the cached reactive is passed to bindEvent(), then the key expression will no longer be reactive; instead, the event expression will be reactive.

Cache scope

By default, when bindCache() is used, it is scoped to the running application. That means that it shares a cache with all user sessions connected to the application (within the R process). This is done with the cache parameter's default value, "app".

With an app-level cache scope, one user can benefit from the work done for another user's session. In most cases, this is the best way to get performance improvements from caching. However, in some cases, this could leak information between sessions. For example, if the cache key does not fully encompass the inputs used by the value, then data could leak between the sessions. Or if a user sees that a cached reactive returns its value very quickly, they may be able to infer that someone else has already used it with the same values.

It is also possible to scope the cache to the session, with cache="session". This removes the risk of information leaking between sessions, but then one session cannot benefit from computations performed in another session.

It is possible to pass in caching objects directly to bindCache(). This can be useful if, for example, you want to use a particular type of cache with specific cached reactives, or if you want to use a cachem::cache_disk() that is shared across multiple processes and persists beyond the current R session.

To use different settings for an application-scoped cache, you can call shinyOptions() at the top of your app.R, server.R, or global.R. For example, this will create a cache with 500 MB of space instead of the default 200 MB:

shinyOptions(cache = cachem::cache_mem(max_size = 500e6))

To use different settings for a session-scoped cache, you can set session$cache at the top of your server function. By default, it will create a 200 MB memory cache for each session, but you can replace it with something different. To use the session-scoped cache, you must also call bindCache() with cache="session". This will create a 100 MB cache for the session:

function(input, output, session) {
  session$cache <- cachem::cache_mem(max_size = 100e6)
  ...
}

If you want to use a cache that is shared across multiple R processes, you can use a cachem::cache_disk(). You can create a application-level shared cache by putting this at the top of your app.R, server.R, or global.R:

shinyOptions(cache = cachem::cache_disk(file.path(dirname(tempdir()), "myapp-cache")))

This will create a subdirectory in your system temp directory named myapp-cache (replace myapp-cache with a unique name of your choosing). On most platforms, this directory will be removed when your system reboots. This cache will persist across multiple starts and stops of the R process, as long as you do not reboot.

To have the cache persist even across multiple reboots, you can create the cache in a location outside of the temp directory. For example, it could be a subdirectory of the application:

shinyOptions(cache = cachem::cache_disk("./myapp-cache"))

In this case, resetting the cache will have to be done manually, by deleting the directory.

You can also scope a cache to just one item, or selected items. To do that, create a cachem::cache_mem() or cachem::cache_disk(), and pass it as the cache argument of bindCache().

Computing cache keys

The actual cache key that is used internally takes value from evaluating the key expression(s) (from the ... arguments) and combines it with the (unevaluated) value expression.

This means that if there are two cached reactives which have the same result from evaluating the key, but different value expressions, then they will not need to worry about collisions.

However, if two cached reactives have identical key and value expressions expressions, they will share the cached values. This is useful when using cache="app": there may be multiple user sessions which create separate cached reactive objects (because they are created from the same code in the server function, but the server function is executed once for each user session), and those cached reactive objects across sessions can share values in the cache.

Async with cached reactives

With a cached reactive expression, the key and/or value expression can be asynchronous. In other words, they can be promises — not regular R promises, but rather objects provided by the promises package, which are similar to promises in JavaScript. (See promises::promise() for more information.) You can also use future::future() objects to run code in a separate process or even on a remote machine.

If the value returns a promise, then anything that consumes the cached reactive must expect it to return a promise.

Similarly, if the key is a promise (in other words, if it is asynchronous), then the entire cached reactive must be asynchronous, since the key must be computed asynchronously before it knows whether to compute the value or the value is retrieved from the cache. Anything that consumes the cached reactive must therefore expect it to return a promise.

Developing render functions for caching

If you've implemented your own ⁠render*()⁠ function, it may just work with bindCache(), but it is possible that you will need to make some modifications. These modifications involve helping bindCache() avoid cache collisions, dealing with internal state that may be set by the, render function, and modifying the data as it goes in and comes out of the cache.

You may need to provide a cacheHint to createRenderFunction() (or htmlwidgets::shinyRenderWidget(), if you've authored an htmlwidget) in order for bindCache() to correctly compute a cache key.

The potential problem is a cache collision. Consider the following:

output$x1 <- renderText({ input$x }) %>% bindCache(input$x)
output$x2 <- renderText({ input$x * 2 }) %>% bindCache(input$x)

Both output$x1 and output$x2 use input$x as part of their cache key, but if it were the only thing used in the cache key, then the two outputs would have a cache collision, and they would have the same output. To avoid this, a cache hint is automatically added when renderText() calls createRenderFunction(). The cache hint is used as part of the actual cache key, in addition to the one passed to bindCache() by the user. The cache hint can be viewed by calling the internal Shiny function extractCacheHint():

r <- renderText({ input$x })
shiny:::extractCacheHint(r)

This returns a nested list containing an item, ⁠$origUserFunc$body⁠, which in this case is the expression which was passed to renderText(): { input$x }. This (quoted) expression is mixed into the actual cache key, and it is how output$x1 does not have collisions with output$x2.

For most developers of render functions, nothing extra needs to be done; the automatic inference of the cache hint is sufficient. Again, you can check it by calling shiny:::extractCacheHint(), and by testing the render function for cache collisions in a real application.

In some cases, however, the automatic cache hint inference is not sufficient, and it is necessary to provide a cache hint. This is true for renderPrint(). Unlike renderText(), it wraps the user-provided expression in another function, before passing it to createRenderFunction() (instead of createRenderFunction()). Because the user code is wrapped in another function, createRenderFunction() is not able to automatically extract the user-provided code and use it in the cache key. Instead, renderPrint calls createRenderFunction(), it explicitly passes along a cacheHint, which includes a label and the original user expression.

In general, if you need to provide a cacheHint, it is best practice to provide a label id, the user's expr, as well as any other arguments that may influence the final value.

For htmlwidgets, it will try to automatically infer a cache hint; again, you can inspect the cache hint with shiny:::extractCacheHint() and also test it in an application. If you do need to explicitly provide a cache hint, pass it to shinyRenderWidget. For example:

renderMyWidget <- function(expr) {
  q <- rlang::enquo0(expr)

  htmlwidgets::shinyRenderWidget(
    q,
    myWidgetOutput,
    quoted = TRUE,
    cacheHint = list(label = "myWidget", userQuo = q)
  )
}

If your render function sets any internal state, you may find it useful in your call to createRenderFunction() to use the cacheWriteHook and/or cacheReadHook parameters. These hooks are functions that run just before the object is stored in the cache, and just after the object is retrieved from the cache. They can modify the data that is stored and retrieved; this can be useful if extra information needs to be stored in the cache. They can also be used to modify the state of the application; for example, it can call createWebDependency() to make JS/CSS resources available if the cached object is loaded in a different R process. (See the source of htmlwidgets::shinyRenderWidget for an example of this.)

Uncacheable objects

Some render functions cannot be cached, typically because they have side effects or modify some external state, and they must re-execute each time in order to work properly.

For developers of such code, they should call createRenderFunction() (or markRenderFunction()) with cacheHint = FALSE.

Caching with renderPlot()

When bindCache() is used with renderPlot(), the height and width passed to the original renderPlot() are ignored. They are superseded by sizePolicy argument passed to 'bindCache. The default is:

sizePolicy = sizeGrowthRatio(width = 400, height = 400, growthRate = 1.2)

sizePolicy must be a function that takes a two-element numeric vector as input, representing the width and height of the ⁠<img>⁠ element in the browser window, and it must return a two-element numeric vector, representing the pixel dimensions of the plot to generate. The purpose is to round the actual pixel dimensions from the browser to some other dimensions, so that this will not generate and cache images of every possible pixel dimension. See sizeGrowthRatio() for more information on the default sizing policy.

See Also

bindEvent(), renderCachedPlot() for caching plots.

Examples

## Not run: 
rc <- bindCache(
  x = reactive({
    Sys.sleep(2)   # Pretend this is expensive
    input$x * 100
  }),
  input$x
)

# Can make it prettier with the %>% operator
library(magrittr)

rc <- reactive({
  Sys.sleep(2)
  input$x * 100
}) %>%
  bindCache(input$x)


## End(Not run)

## Only run app examples in interactive R sessions
if (interactive()) {

# Basic example
shinyApp(
  ui = fluidPage(
    sliderInput("x", "x", 1, 10, 5),
    sliderInput("y", "y", 1, 10, 5),
    div("x * y: "),
    verbatimTextOutput("txt")
  ),
  server = function(input, output) {
    r <- reactive({
      # The value expression is an _expensive_ computation
      message("Doing expensive computation...")
      Sys.sleep(2)
      input$x * input$y
    }) %>%
      bindCache(input$x, input$y)

    output$txt <- renderText(r())
  }
)


# Caching renderText
shinyApp(
  ui = fluidPage(
    sliderInput("x", "x", 1, 10, 5),
    sliderInput("y", "y", 1, 10, 5),
    div("x * y: "),
    verbatimTextOutput("txt")
  ),
  server = function(input, output) {
    output$txt <- renderText({
      message("Doing expensive computation...")
      Sys.sleep(2)
      input$x * input$y
    }) %>%
      bindCache(input$x, input$y)
  }
)


# Demo of using events and caching with an actionButton
shinyApp(
  ui = fluidPage(
    sliderInput("x", "x", 1, 10, 5),
    sliderInput("y", "y", 1, 10, 5),
    actionButton("go", "Go"),
    div("x * y: "),
    verbatimTextOutput("txt")
  ),
  server = function(input, output) {
    r <- reactive({
      message("Doing expensive computation...")
      Sys.sleep(2)
      input$x * input$y
    }) %>%
      bindCache(input$x, input$y) %>%
      bindEvent(input$go)
      # The cached, eventified reactive takes a reactive dependency on
      # input$go, but doesn't use it for the cache key. It uses input$x and
      # input$y for the cache key, but doesn't take a reactive dependency on
      # them, because the reactive dependency is superseded by addEvent().

    output$txt <- renderText(r())
  }
)

}

Make an object respond only to specified reactive events

Description

Modify an object to respond to "event-like" reactive inputs, values, and expressions. bindEvent() can be used with reactive expressions, render functions, and observers. The resulting object takes a reactive dependency on the ... arguments, and not on the original object's code. This can, for example, be used to make an observer execute only when a button is pressed.

bindEvent() was added in Shiny 1.6.0. When it is used with reactive() and observe(), it does the same thing as eventReactive() and observeEvent(). However, bindEvent() is more flexible: it can be combined with bindCache(), and it can also be used with render functions (like renderText() and renderPlot()).

Usage

bindEvent(
  x,
  ...,
  ignoreNULL = TRUE,
  ignoreInit = FALSE,
  once = FALSE,
  label = NULL
)

Arguments

Details

Shiny's reactive programming framework is primarily designed for calculated values (reactive expressions) and side-effect-causing actions (observers) that respond to any of their inputs changing. That's often what is desired in Shiny apps, but not always: sometimes you want to wait for a specific action to be taken from the user, like clicking an actionButton(), before calculating an expression or taking an action. A reactive value or expression that is used to trigger other calculations in this way is called an event.

These situations demand a more imperative, "event handling" style of programming that is possible–but not particularly intuitive–using the reactive programming primitives observe() and isolate(). bindEvent() provides a straightforward API for event handling that wraps observe and isolate.

The ... arguments are captured as expressions and combined into an event expression. When this event expression is invalidated (when its upstream reactive inputs change), that is an event, and it will cause the original object's code to execute.

Use bindEvent() with observe() whenever you want to perform an action in response to an event. (This does the same thing as observeEvent(), which was available in Shiny prior to version 1.6.0.) Note that "recalculate a value" does not generally count as performing an action – use reactive() for that.

Use bindEvent() with reactive() to create a calculated value that only updates in response to an event. This is just like a normal reactive expression except it ignores all the usual invalidations that come from its reactive dependencies; it only invalidates in response to the given event. (This does the same thing as eventReactive(), which was available in Shiny prior to version 1.6.0.)

bindEvent() is often used with bindCache().

ignoreNULL and ignoreInit

bindEvent() takes an ignoreNULL parameter that affects behavior when the event expression evaluates to NULL (or in the special case of an actionButton(), 0). In these cases, if ignoreNULL is TRUE, then it will raise a silent validation error. This is useful behavior if you don't want to do the action or calculation when your app first starts, but wait for the user to initiate the action first (like a "Submit" button); whereas ignoreNULL=FALSE is desirable if you want to initially perform the action/calculation and just let the user re-initiate it (like a "Recalculate" button).

bindEvent() also takes an ignoreInit argument. By default, reactive expressions and observers will run on the first reactive flush after they are created (except if, at that moment, the event expression evaluates to NULL and ignoreNULL is TRUE). But when responding to a click of an action button, it may often be useful to set ignoreInit to TRUE. For example, if you're setting up an observer to respond to a dynamically created button, then ignoreInit = TRUE will guarantee that the action will only be triggered when the button is actually clicked, instead of also being triggered when it is created/initialized. Similarly, if you're setting up a reactive that responds to a dynamically created button used to refresh some data (which is then returned by that reactive), then you should use reactive(...) %>% bindEvent(..., ignoreInit = TRUE) if you want to let the user decide if/when they want to refresh the data (since, depending on the app, this may be a computationally expensive operation).

Even though ignoreNULL and ignoreInit can be used for similar purposes they are independent from one another. Here's the result of combining these:

ignoreNULL = TRUE and ignoreInit = FALSE

This is the default. This combination means that reactive/observer code will run every time that event expression is not NULL. If, at the time of creation, the event expression happens to not be NULL, then the code runs.

ignoreNULL = FALSE and ignoreInit = FALSE

This combination means that reactive/observer code will run every time no matter what.

ignoreNULL = FALSE and ignoreInit = TRUE

This combination means that reactive/observer code will not run at the time of creation (because ignoreInit = TRUE), but it will run every other time.

ignoreNULL = TRUE and ignoreInit = TRUE

This combination means that reactive/observer code will not at the time of creation (because ignoreInit = TRUE). After that, the reactive/observer code will run every time that the event expression is not NULL.

Types of objects

bindEvent() can be used with reactive expressions, observers, and shiny render functions.

When bindEvent() is used with reactive(), it creates a new reactive expression object.

When bindEvent() is used with observe(), it alters the observer in place. It can only be used with observers which have not yet executed.

Combining events and caching

In many cases, it makes sense to use bindEvent() along with bindCache(), because they each can reduce the amount of work done on the server. For example, you could have sliderInputs x and y and a reactive() that performs a time-consuming operation with those values. Using bindCache() can speed things up, especially if there are multiple users. But it might make sense to also not do the computation until the user sets both x and y, and then clicks on an actionButton named go.

To use both caching and events, the object should first be passed to bindCache(), then bindEvent(). For example:

r <- reactive({
   Sys.sleep(2)  # Pretend this is an expensive computation
   input$x * input$y
 }) %>%
 bindCache(input$x, input$y) %>%
 bindEvent(input$go)

Anything that consumes r() will take a reactive dependency on the event expression given to bindEvent(), and not the cache key expression given to bindCache(). In this case, it is just input$go.

Create a button for bookmarking/sharing

Description

A bookmarkButton is a actionButton() with a default label that consists of a link icon and the text "Bookmark...". It is meant to be used for bookmarking state.

Usage

bookmarkButton(
  label = "Bookmark...",
  icon = shiny::icon("link", lib = "glyphicon"),
  title = "Bookmark this application's state and get a URL for sharing.",
  ...,
  id = "._bookmark_"
)

Arguments

See Also

enableBookmarking() for more examples.

Examples

## Only run these examples in interactive sessions
if (interactive()) {

# This example shows how to use multiple bookmark buttons. If you only need
# a single bookmark button, see examples in ?enableBookmarking.
ui <- function(request) {
  fluidPage(
    tabsetPanel(id = "tabs",
      tabPanel("One",
        checkboxInput("chk1", "Checkbox 1"),
        bookmarkButton(id = "bookmark1")
      ),
      tabPanel("Two",
        checkboxInput("chk2", "Checkbox 2"),
        bookmarkButton(id = "bookmark2")
      )
    )
  )
}
server <- function(input, output, session) {
  # Need to exclude the buttons from themselves being bookmarked
  setBookmarkExclude(c("bookmark1", "bookmark2"))

  # Trigger bookmarking with either button
  observeEvent(input$bookmark1, {
    session$doBookmark()
  })
  observeEvent(input$bookmark2, {
    session$doBookmark()
  })
}
enableBookmarking(store = "url")
shinyApp(ui, server)
}

Bootstrap libraries

Description

This function defines a set of web dependencies necessary for using Bootstrap components in a web page.

Usage

bootstrapLib(theme = NULL)

Arguments

Details

It isn't necessary to call this function if you use bootstrapPage() or others which use bootstrapPage, such fluidPage(), navbarPage(), fillPage(), etc, because they already include the Bootstrap web dependencies.

Create a Bootstrap page

Description

Create a Shiny UI page that loads the CSS and JavaScript for Bootstrap, and has no content in the page body (other than what you provide).

Usage

bootstrapPage(..., title = NULL, theme = NULL, lang = NULL)

basicPage(...)

Arguments

Details

This function is primarily intended for users who are proficient in HTML/CSS, and know how to lay out pages in Bootstrap. Most applications should use fluidPage() along with layout functions like fluidRow() and sidebarLayout().

Value

A UI definition that can be passed to the shinyUI function.

Note

The basicPage function is deprecated, you should use the fluidPage() function instead.

See Also

fluidPage(), fixedPage()

Find rows of data selected on an interactive plot.

Description

brushedPoints() returns rows from a data frame which are under a brush. nearPoints() returns rows from a data frame which are near a click, hover, or double-click. Alternatively, set allRows = TRUE to return all rows from the input data with an additional column selected_ that indicates which rows of the would be selected.

Usage

brushedPoints(
  df,
  brush,
  xvar = NULL,
  yvar = NULL,
  panelvar1 = NULL,
  panelvar2 = NULL,
  allRows = FALSE
)

nearPoints(
  df,
  coordinfo,
  xvar = NULL,
  yvar = NULL,
  panelvar1 = NULL,
  panelvar2 = NULL,
  threshold = 5,
  maxpoints = NULL,
  addDist = FALSE,
  allRows = FALSE
)

Arguments

Value

A data frame based on df, containing the observations selected by the brush or near the click event. For nearPoints(), the rows will be sorted by distance to the event.

If allRows = TRUE, then all rows will returned, along with a new selected_ column that indicates whether or not the point was selected. The output from nearPoints() will no longer be sorted, but you can set addDist = TRUE to get an additional column that gives the pixel distance to the pointer.

ggplot2

For plots created with ggplot2, it is not necessary to specify the column names to xvar, yvar, panelvar1, and panelvar2 as that information can be automatically derived from the plot specification.

Note, however, that this will not work if you use a computed column, like ⁠aes(speed/2, dist))⁠. Instead, we recommend that you modify the data first, and then make the plot with "raw" columns in the modified data.

Brushing

If x or y column is a factor, then it will be coerced to an integer vector. If it is a character vector, then it will be coerced to a factor and then integer vector. This means that the brush will be considered to cover a given character/factor value when it covers the center value.

If the brush is operating in just the x or y directions (e.g., with brushOpts(direction = "x"), then this function will filter out points using just the x or y variable, whichever is appropriate.

See Also

plotOutput() for example usage.

Examples

## Not run: 
# Note that in practice, these examples would need to go in reactives
# or observers.

# This would select all points within 5 pixels of the click
nearPoints(mtcars, input$plot_click)

# Select just the nearest point within 10 pixels of the click
nearPoints(mtcars, input$plot_click, threshold = 10, maxpoints = 1)


## End(Not run)

Create an object representing brushing options

Description

This generates an object representing brushing options, to be passed as the brush argument of imageOutput() or plotOutput().

Usage

brushOpts(
  id,
  fill = "#9cf",
  stroke = "#036",
  opacity = 0.25,
  delay = 300,
  delayType = c("debounce", "throttle"),
  clip = TRUE,
  direction = c("xy", "x", "y"),
  resetOnNew = FALSE
)

Arguments

See Also

clickOpts() for clicking events.

Customize busy indicator options

Description

Shiny automatically includes busy indicators, which more specifically means:

1. Calculating/recalculating outputs have a spinner overlay.

2. Outputs fade out/in when recalculating.

3. When no outputs are calculating/recalculating, but Shiny is busy doing something else (e.g., a download, side-effect, etc), a page-level pulsing banner is shown.

This function allows you to customize the appearance of these busy indicators by including the result of this function inside the app's UI. Note that, unless spinner_selector (or fade_selector) is specified, the spinner/fade customization applies to the parent element. If the customization should instead apply to the entire page, set spinner_selector = 'html' and fade_selector = 'html'.

Usage

busyIndicatorOptions(
  ...,
  spinner_type = NULL,
  spinner_color = NULL,
  spinner_size = NULL,
  spinner_delay = NULL,
  spinner_selector = NULL,
  fade_opacity = NULL,
  fade_selector = NULL,
  pulse_background = NULL,
  pulse_height = NULL,
  pulse_speed = NULL
)

Arguments

See Also

useBusyIndicators() to disable/enable busy indicators.

Examples

library(bslib)

card_ui <- function(id, spinner_type = id) {
  card(
    busyIndicatorOptions(spinner_type = spinner_type),
    card_header(paste("Spinner:", spinner_type)),
    plotOutput(shiny::NS(id, "plot"))
  )
}

card_server <- function(id, simulate = reactive()) {
  moduleServer(
    id = id,
    function(input, output, session) {
      output$plot <- renderPlot({
        Sys.sleep(1)
        simulate()
        plot(x = rnorm(100), y = rnorm(100))
      })
    }
  )
}

ui <- page_fillable(
  useBusyIndicators(),
  input_task_button("simulate", "Simulate", icon = icon("refresh")),
  layout_columns(
    card_ui("ring"),
    card_ui("bars"),
    card_ui("dots"),
    card_ui("pulse"),
    col_widths = 6
  )
)

server <- function(input, output, session) {
  simulate <- reactive(input$simulate)
  card_server("ring", simulate)
  card_server("bars", simulate)
  card_server("dots", simulate)
  card_server("pulse", simulate)
}

shinyApp(ui, server)

Invoke a Shiny module

Description

Note: As of Shiny 1.5.0, we recommend using moduleServer() instead of callModule(), because the syntax is a little easier to understand, and modules created with moduleServer can be tested with testServer().

Usage

callModule(module, id, ..., session = getDefaultReactiveDomain())

Arguments

Value

The return value, if any, from executing the module server function

Checkbox Group Input Control

Description

Create a group of checkboxes that can be used to toggle multiple choices independently. The server will receive the input as a character vector of the selected values.

Usage

checkboxGroupInput(
  inputId,
  label,
  choices = NULL,
  selected = NULL,
  inline = FALSE,
  width = NULL,
  choiceNames = NULL,
  choiceValues = NULL
)

Arguments

Value

A list of HTML elements that can be added to a UI definition.

Server value

Character vector of values corresponding to the boxes that are checked.

See Also

checkboxInput(), updateCheckboxGroupInput()

Other input elements: actionButton(), checkboxInput(), dateInput(), dateRangeInput(), fileInput(), numericInput(), passwordInput(), radioButtons(), selectInput(), sliderInput(), submitButton(), textAreaInput(), textInput(), varSelectInput()

Examples

## Only run examples in interactive R sessions
if (interactive()) {

ui <- fluidPage(
  checkboxGroupInput("variable", "Variables to show:",
                     c("Cylinders" = "cyl",
                       "Transmission" = "am",
                       "Gears" = "gear")),
  tableOutput("data")
)

server <- function(input, output, session) {
  output$data <- renderTable({
    mtcars[, c("mpg", input$variable), drop = FALSE]
  }, rownames = TRUE)
}

shinyApp(ui, server)

ui <- fluidPage(
  checkboxGroupInput("icons", "Choose icons:",
    choiceNames =
      list(icon("calendar"), icon("bed"),
           icon("cog"), icon("bug")),
    choiceValues =
      list("calendar", "bed", "cog", "bug")
  ),
  textOutput("txt")
)

server <- function(input, output, session) {
  output$txt <- renderText({
    icons <- paste(input$icons, collapse = ", ")
    paste("You chose", icons)
  })
}

shinyApp(ui, server)
}

Checkbox Input Control

Description

Create a checkbox that can be used to specify logical values.

Usage

checkboxInput(inputId, label, value = FALSE, width = NULL)

Arguments

Value

A checkbox control that can be added to a UI definition.

Server value

TRUE if checked, FALSE otherwise.

See Also

checkboxGroupInput(), updateCheckboxInput()

Other input elements: actionButton(), checkboxGroupInput(), dateInput(), dateRangeInput(), fileInput(), numericInput(), passwordInput(), radioButtons(), selectInput(), sliderInput(), submitButton(), textAreaInput(), textInput(), varSelectInput()

Examples

## Only run examples in interactive R sessions
if (interactive()) {

ui <- fluidPage(
  checkboxInput("somevalue", "Some value", FALSE),
  verbatimTextOutput("value")
)
server <- function(input, output) {
  output$value <- renderText({ input$somevalue })
}
shinyApp(ui, server)
}

Control interactive plot point events

Description

These functions give control over the click, dblClick and hover events generated by imageOutput() and plotOutput().

Usage

clickOpts(id, clip = TRUE)

dblclickOpts(id, clip = TRUE, delay = 400)

hoverOpts(
  id,
  delay = 300,
  delayType = c("debounce", "throttle"),
  clip = TRUE,
  nullOutside = TRUE
)

Arguments

See Also

brushOpts() for brushing events.

Create a column within a UI definition

Description

Create a column for use within a fluidRow() or fixedRow()

Usage

column(width, ..., offset = 0)

Arguments

Value

A column that can be included within a fluidRow() or fixedRow().

See Also

fluidRow(), fixedRow().

Examples

## Only run examples in interactive R sessions
if (interactive()) {

ui <- fluidPage(
  fluidRow(
    column(4,
      sliderInput("obs", "Number of observations:",
                  min = 1, max = 1000, value = 500)
    ),
    column(8,
      plotOutput("distPlot")
    )
  )
)

server <- function(input, output) {
  output$distPlot <- renderPlot({
    hist(rnorm(input$obs))
  })
}

shinyApp(ui, server)



ui <- fluidPage(
  fluidRow(
    column(width = 4,
      "4"
    ),
    column(width = 3, offset = 2,
      "3 offset 2"
    )
  )
)
shinyApp(ui, server = function(input, output) { })
}

Conditional Panel

Description

Creates a panel that is visible or not, depending on the value of a JavaScript expression. The JS expression is evaluated once at startup and whenever Shiny detects a relevant change in input/output.

Usage

conditionalPanel(condition, ..., ns = NS(NULL))

Arguments

Details

In the JS expression, you can refer to input and output JavaScript objects that contain the current values of input and output. For example, if you have an input with an id of foo, then you can use input.foo to read its value. (Be sure not to modify the input/output objects, as this may cause unpredictable behavior.)

Note

You are not recommended to use special JavaScript characters such as a period . in the input id's, but if you do use them anyway, for example, inputId = "foo.bar", you will have to use input["foo.bar"] instead of input.foo.bar to read the input value.

Examples

## Only run this example in interactive R sessions
if (interactive()) {
  ui <- fluidPage(
    sidebarPanel(
      selectInput("plotType", "Plot Type",
        c(Scatter = "scatter", Histogram = "hist")
      ),
      # Only show this panel if the plot type is a histogram
      conditionalPanel(
        condition = "input.plotType == 'hist'",
        selectInput(
          "breaks", "Breaks",
          c("Sturges", "Scott", "Freedman-Diaconis", "[Custom]" = "custom")
        ),
        # Only show this panel if Custom is selected
        conditionalPanel(
          condition = "input.breaks == 'custom'",
          sliderInput("breakCount", "Break Count", min = 1, max = 50, value = 10)
        )
      )
    ),
    mainPanel(
      plotOutput("plot")
    )
  )

  server <- function(input, output) {
    x <- rnorm(100)
    y <- rnorm(100)

    output$plot <- renderPlot({
      if (input$plotType == "scatter") {
        plot(x, y)
      } else {
        breaks <- input$breaks
        if (breaks == "custom") {
          breaks <- input$breakCount
        }

        hist(x, breaks = breaks)
      }
    })
  }

  shinyApp(ui, server)
}

Implement custom render functions

Description

Developer-facing utilities for implementing a custom renderXXX() function. Before using these utilities directly, consider using the htmlwidgets package to implement custom outputs (i.e., custom renderXXX()/xxxOutput() functions). That said, these utilities can be used more directly if a full-blown htmlwidget isn't needed and/or the user-supplied reactive expression needs to be wrapped in additional call(s).

Usage

createRenderFunction(
  func,
  transform = function(value, session, name, ...) value,
  outputFunc = NULL,
  outputArgs = NULL,
  cacheHint = "auto",
  cacheWriteHook = NULL,
  cacheReadHook = NULL
)

quoToFunction(q, label = sys.call(-1)[[1]], ..stacktraceon = FALSE)

installExprFunction(
  expr,
  name,
  eval.env = parent.frame(2),
  quoted = FALSE,
  assign.env = parent.frame(1),
  label = sys.call(-1)[[1]],
  wrappedWithLabel = TRUE,
  ..stacktraceon = FALSE
)

Arguments

Details

To implement a custom renderXXX() function, essentially 2 things are needed:

1. Capture the user's reactive expression as a function.

   • New renderXXX() functions can use quoToFunction() for this, but already existing renderXXX() functions that contain env and quoted parameters may want to continue using installExprFunction() for better legacy support (see examples).

2. Flag the resulting function (from 1) as a Shiny rendering function and also provide a UI container for displaying the result of the rendering function.

   • createRenderFunction() is currently recommended (instead of markRenderFunction()) for this step (see examples).

Value

An annotated render function, ready to be assigned to an output slot.

Functions

• quoToFunction(): convert a quosure to a function.

• installExprFunction(): converts a user's reactive expr into a function that's assigned to a name in the assign.env.

Examples

# A custom render function that repeats the supplied value 3 times
renderTriple <- function(expr) {
  # Wrap user-supplied reactive expression into a function
  func <- quoToFunction(rlang::enquo0(expr))

  createRenderFunction(
    func,
    transform = function(value, session, name, ...) {
      paste(rep(value, 3), collapse=", ")
    },
    outputFunc = textOutput
  )
}

# For better legacy support, consider using installExprFunction() over quoToFunction()
renderTripleLegacy <- function(expr, env = parent.frame(), quoted = FALSE) {
  func <- installExprFunction(expr, "func", env, quoted)

  createRenderFunction(
    func,
    transform = function(value, session, name, ...) {
      paste(rep(value, 3), collapse=", ")
    },
    outputFunc = textOutput
  )
}

# Test render function from the console
reactiveConsole(TRUE)

v <- reactiveVal("basic")
r <- renderTriple({ v() })
r()
#> [1] "basic, basic, basic"

# User can supply quoted code via rlang::quo(). Note that evaluation of the
# expression happens when r2() is invoked, not when r2 is created.
q <- rlang::quo({ v() })
r2 <- rlang::inject(renderTriple(!!q))
v("rlang")
r2()
#> [1] "rlang, rlang, rlang"

# Supplying quoted code without rlang::quo() requires installExprFunction()
expr <- quote({ v() })
r3 <- renderTripleLegacy(expr, quoted = TRUE)
v("legacy")
r3()
#> [1] "legacy, legacy, legacy"

# The legacy approach also supports with quosures (env is ignored in this case)
q <- rlang::quo({ v() })
r4 <- renderTripleLegacy(q, quoted = TRUE)
v("legacy-rlang")
r4()
#> [1] "legacy-rlang, legacy-rlang, legacy-rlang"

# Turn off reactivity in the console
reactiveConsole(FALSE)

Create a web dependency

Description

Ensure that a file-based HTML dependency (from the htmltools package) can be served over Shiny's HTTP server. This function works by using addResourcePath() to map the HTML dependency's directory to a URL.

Usage

createWebDependency(dependency, scrubFile = TRUE)

Arguments

Value

A single HTML dependency object that has an href-named element in its src.

Table output with the JavaScript DataTables library

Description

This function is deprecated, use DT::renderDT() instead. It provides a superset of functionality, better performance, and better user experience.

Usage

dataTableOutput(outputId)

renderDataTable(
  expr,
  options = NULL,
  searchDelay = 500,
  callback = "function(oTable) {}",
  escape = TRUE,
  env = parent.frame(),
  quoted = FALSE,
  outputArgs = list()
)

Arguments

Examples

## Only run this example in interactive R sessions
if (interactive()) {
  # pass a callback function to DataTables using I()
  shinyApp(
    ui = fluidPage(
      fluidRow(
        column(12,
          dataTableOutput('table')
        )
      )
    ),
    server = function(input, output) {
      output$table <- renderDataTable(iris,
        options = list(
          pageLength = 5,
          initComplete = I("function(settings, json) {alert('Done.');}")
        )
      )
    }
  )
}

Create date input

Description

Creates a text input which, when clicked on, brings up a calendar that the user can click on to select dates.

Usage

dateInput(
  inputId,
  label,
  value = NULL,
  min = NULL,
  max = NULL,
  format = "yyyy-mm-dd",
  startview = "month",
  weekstart = 0,
  language = "en",
  width = NULL,
  autoclose = TRUE,
  datesdisabled = NULL,
  daysofweekdisabled = NULL
)

Arguments

Details

The date format string specifies how the date will be displayed in the browser. It allows the following values:

• yy Year without century (12)

• yyyy Year with century (2012)

• mm Month number, with leading zero (01-12)

• m Month number, without leading zero (1-12)

• M Abbreviated month name

• MM Full month name

• dd Day of month with leading zero

• d Day of month without leading zero

• D Abbreviated weekday name

• DD Full weekday name

Server value

A Date vector of length 1.

See Also

dateRangeInput(), updateDateInput()

Other input elements: actionButton(), checkboxGroupInput(), checkboxInput(), dateRangeInput(), fileInput(), numericInput(), passwordInput(), radioButtons(), selectInput(), sliderInput(), submitButton(), textAreaInput(), textInput(), varSelectInput()

Examples

## Only run examples in interactive R sessions
if (interactive()) {

ui <- fluidPage(
  dateInput("date1", "Date:", value = "2012-02-29"),

  # Default value is the date in client's time zone
  dateInput("date2", "Date:"),

  # value is always yyyy-mm-dd, even if the display format is different
  dateInput("date3", "Date:", value = "2012-02-29", format = "mm/dd/yy"),

  # Pass in a Date object
  dateInput("date4", "Date:", value = Sys.Date()-10),

  # Use different language and different first day of week
  dateInput("date5", "Date:",
          language = "ru",
          weekstart = 1),

  # Start with decade view instead of default month view
  dateInput("date6", "Date:",
            startview = "decade"),

  # Disable Mondays and Tuesdays.
  dateInput("date7", "Date:", daysofweekdisabled = c(1,2)),

  # Disable specific dates.
  dateInput("date8", "Date:", value = "2012-02-29",
            datesdisabled = c("2012-03-01", "2012-03-02"))
)

shinyApp(ui, server = function(input, output) { })
}

Create date range input

Description

Creates a pair of text inputs which, when clicked on, bring up calendars that the user can click on to select dates.

Usage

dateRangeInput(
  inputId,
  label,
  start = NULL,
  end = NULL,
  min = NULL,
  max = NULL,
  format = "yyyy-mm-dd",
  startview = "month",
  weekstart = 0,
  language = "en",
  separator = " to ",
  width = NULL,
  autoclose = TRUE
)

Arguments

Details

The date format string specifies how the date will be displayed in the browser. It allows the following values:

• yy Year without century (12)

• yyyy Year with century (2012)

• mm Month number, with leading zero (01-12)

• m Month number, without leading zero (1-12)

• M Abbreviated month name

• MM Full month name

• dd Day of month with leading zero

• d Day of month without leading zero

• D Abbreviated weekday name

• DD Full weekday name

Server value

A Date vector of length 2.

See Also

dateInput(), updateDateRangeInput()

Other input elements: actionButton(), checkboxGroupInput(), checkboxInput(), dateInput(), fileInput(), numericInput(), passwordInput(), radioButtons(), selectInput(), sliderInput(), submitButton(), textAreaInput(), textInput(), varSelectInput()

Examples

## Only run examples in interactive R sessions
if (interactive()) {

ui <- fluidPage(
  dateRangeInput("daterange1", "Date range:",
                 start = "2001-01-01",
                 end   = "2010-12-31"),

  # Default start and end is the current date in the client's time zone
  dateRangeInput("daterange2", "Date range:"),

  # start and end are always specified in yyyy-mm-dd, even if the display
  # format is different
  dateRangeInput("daterange3", "Date range:",
                 start  = "2001-01-01",
                 end    = "2010-12-31",
                 min    = "2001-01-01",
                 max    = "2012-12-21",
                 format = "mm/dd/yy",
                 separator = " - "),

  # Pass in Date objects
  dateRangeInput("daterange4", "Date range:",
                 start = Sys.Date()-10,
                 end = Sys.Date()+10),

  # Use different language and different first day of week
  dateRangeInput("daterange5", "Date range:",
                 language = "de",
                 weekstart = 1),

  # Start with decade view instead of default month view
  dateRangeInput("daterange6", "Date range:",
                 startview = "decade")
)

shinyApp(ui, server = function(input, output) { })
}

Slow down a reactive expression with debounce/throttle

Description

Transforms a reactive expression by preventing its invalidation signals from being sent unnecessarily often. This lets you ignore a very "chatty" reactive expression until it becomes idle, which is useful when the intermediate values don't matter as much as the final value, and the downstream calculations that depend on the reactive expression take a long time. debounce and throttle use different algorithms for slowing down invalidation signals; see Details.

Usage

debounce(r, millis, priority = 100, domain = getDefaultReactiveDomain())

throttle(r, millis, priority = 100, domain = getDefaultReactiveDomain())

Arguments

Details

This is not a true debounce/throttle in that it will not prevent r from being called many times (in fact it may be called more times than usual), but rather, the reactive invalidation signal that is produced by r is debounced/throttled instead. Therefore, these functions should be used when r is cheap but the things it will trigger (downstream outputs and reactives) are expensive.

Debouncing means that every invalidation from r will be held for the specified time window. If r invalidates again within that time window, then the timer starts over again. This means that as long as invalidations continually arrive from r within the time window, the debounced reactive will not invalidate at all. Only after the invalidations stop (or slow down sufficiently) will the downstream invalidation be sent.

⁠ooo-oo-oo---- => -----------o-⁠

(In this graphical depiction, each character represents a unit of time, and the time window is 3 characters.)

Throttling, on the other hand, delays invalidation if the throttled reactive recently (within the time window) invalidated. New r invalidations do not reset the time window. This means that if invalidations continually come from r within the time window, the throttled reactive will invalidate regularly, at a rate equal to or slower than the time window.

⁠ooo-oo-oo---- => o--o--o--o---⁠

Limitations

Because R is single threaded, we can't come close to guaranteeing that the timing of debounce/throttle (or any other timing-related functions in Shiny) will be consistent or accurate; at the time we want to emit an invalidation signal, R may be performing a different task and we have no way to interrupt it (nor would we necessarily want to if we could). Therefore, it's best to think of the time windows you pass to these functions as minimums.

You may also see undesirable behavior if the amount of time spent doing downstream processing for each change approaches or exceeds the time window: in this case, debounce/throttle may not have any effect, as the time each subsequent event is considered is already after the time window has expired.

Examples

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

library(shiny)
library(magrittr)

ui <- fluidPage(
  plotOutput("plot", click = clickOpts("hover")),
  helpText("Quickly click on the plot above, while watching the result table below:"),
  tableOutput("result")
)

server <- function(input, output, session) {
  hover <- reactive({
    if (is.null(input$hover))
      list(x = NA, y = NA)
    else
      input$hover
  })
  hover_d <- hover %>% debounce(1000)
  hover_t <- hover %>% throttle(1000)

  output$plot <- renderPlot({
    plot(cars)
  })

  output$result <- renderTable({
    data.frame(
      mode = c("raw", "throttle", "debounce"),
      x = c(hover()$x, hover_t()$x, hover_d()$x),
      y = c(hover()$y, hover_t()$y, hover_d()$y)
    )
  })
}

shinyApp(ui, server)
}

Shiny Developer Mode

Description

Developer Mode enables a number of options() to make a developer's life easier, like enabling non-minified JS and printing messages about deprecated functions and options.

Shiny Developer Mode can be enabled by calling devmode(TRUE) and disabled by calling devmode(FALSE).

Please see the function descriptions for more details.

Usage

devmode(
  devmode = getOption("shiny.devmode", TRUE),
  verbose = getOption("shiny.devmode.verbose", TRUE)
)

in_devmode()

with_devmode(devmode, code, verbose = getOption("shiny.devmode.verbose", TRUE))

devmode_inform(
  message,
  .frequency = "regularly",
  .frequency_id = message,
  .file = stderr(),
  ...
)

register_devmode_option(name, devmode_message = NULL, devmode_default = NULL)

get_devmode_option(
  name,
  default = NULL,
  devmode_default = missing_arg(),
  devmode_message = missing_arg()
)

Arguments

Functions

• devmode(): Function to set two options to enable/disable Shiny Developer Mode and Developer messages

• in_devmode(): Determines if Shiny is in Developer Mode. If the getOption("shiny.devmode") is set to TRUE and not in testing inside testthat, then Shiny Developer Mode is enabled.

• with_devmode(): Temporarily set Shiny Developer Mode and Developer message verbosity

• devmode_inform(): If Shiny Developer Mode and verbosity are enabled, displays a message once every 8 hrs (by default)

• register_devmode_option(): Registers a Shiny Developer Mode option with an updated value and Developer message. This registration method allows package authors to write one message in a single location.

  For example, the following Shiny Developer Mode options are registered:

  # Reload the Shiny app when a sourced R file changes
  register_devmode_option(
    "shiny.autoreload",
    "Turning on shiny autoreload. To disable, call `options(shiny.autoreload = FALSE)`",
    devmode_default = TRUE
  )
  
  # Use the unminified Shiny JavaScript file, `shiny.js`
  register_devmode_option(
    "shiny.minified",
    "Using full shiny javascript file. To use the minified version, call `options(shiny.minified = TRUE)`",
    devmode_default = FALSE
  )
  
  # Display the full stack trace when errors occur during Shiny app execution
  register_devmode_option(
    "shiny.fullstacktrace",
    "Turning on full stack trace. To disable, call `options(shiny.fullstacktrace = FALSE)`",
    devmode_default = TRUE
  )
  

  Other known, non-Shiny Developer Mode options:

  • Sass:

  # Display the full stack trace when errors occur during Shiny app execution
  register_devmode_option(
    "sass.cache",
    "Turning off sass cache. To use default caching, call `options(sass.cache = TRUE)`",
    devmode_default = FALSE
  )
  

• get_devmode_option(): Provides a consistent way to change the expected getOption() behavior when Developer Mode is enabled. This method is very similar to getOption() where the globally set option takes precedence. See section "Avoiding direct dependency on shiny" for get_devmode_option() implementation details.

  Package developers: Register your Dev Mode option using register_devmode_option() to avoid supplying the same devmode_default and devmode_message values throughout your package. (This requires a shiny dependency.)

Avoiding direct dependency on shiny

The methods explained in this help file act independently from the rest of Shiny but are included to provide blue prints for your own packages. If your package already has (or is willing to take) a dependency on Shiny, we recommend using the exported Shiny methods for consistent behavior. Note that if you use exported Shiny methods, it will cause the Shiny package to load. This may be undesirable if your code will be used in (for example) R Markdown documents that do not have a Shiny runtime (runtime: shiny).

If your package can not take a dependency on Shiny, we recommending re-implementing these two functions:

1. in_devmode():

   This function should return TRUE if getOption("shiny.devmode") is set. In addition, we strongly recommend that it also checks to make sure testthat is not testing.

   in_devmode <- function() {
     isTRUE(getOption("shiny.devmode", FALSE)) &&
       !identical(Sys.getenv("TESTTHAT"), "true")
   }
   

2. get_devmode_option(name, default, devmode_default, devmode_message):

   This function is similar to getOption(name, default), but when the option is not set, the default value changes depending on the Dev Mode. get_devmode_option() should be implemented as follows:

   • If not in Dev Mode:

     • Return getOption(name, default).

   • If in Dev Mode:

     • Get the global option getOption(name) value.

     • If the global option value is set:

       • Return the value.

     • If the global option value is not set:

       • Notify the developer that the Dev Mode default value will be used.

       • Return the Dev Mode default value.

   When notifying the developer that the default value has changed, we strongly recommend displaying a message (devmode_message) to stderr() once every 8 hours using rlang::inform(). This will keep the author up to date as to which Dev Mode options are being altered. To allow developers a chance to disable Dev Mode messages, the message should be skipped if getOption("shiny.devmode.verbose", TRUE) is not TRUE.

   get_devmode_option <- function(name, default = NULL, devmode_default, devmode_message) {
     if (!in_devmode()) {
       # Dev Mode disabled, act like `getOption()`
       return(getOption(name, default = default))
     }
   
     # Dev Mode enabled, update the default value for `getOption()`
     getOption(name, default = {
       # Notify developer
       if (
         !missing(devmode_message) &&
         !is.null(devmode_message) &&
         getOption("shiny.devmode.verbose", TRUE)
       ) {
         rlang::inform(
           message = devmode_message,
           .frequency = "regularly",
           .frequency_id = devmode_message,
           .file = stderr()
         )
       }
   
       # Return Dev Mode default value `devmode_default`
       devmode_default
     })
   }
   

The remaining functions in this file are used for author convenience and are not recommended for all reimplementation situations.

Examples

# Enable Shiny Developer mode
devmode()

in_devmode() # TRUE/FALSE?

# Execute code in a temporary shiny dev mode
with_devmode(TRUE, in_devmode()) # TRUE

# Ex: Within shiny, we register the option "shiny.minified"
#   to default to `FALSE` when in Dev Mode
## Not run: register_devmode_option(
  "shiny.minified",
  devmode_message = paste0(
    "Using full shiny javascript file. ",
    "To use the minified version, call `options(shiny.minified = TRUE)`"
  ),
  devmode_default = FALSE
)
## End(Not run)

# Used within `shiny::runApp(launch.browser)`
get_devmode_option("shiny.minified", TRUE) # TRUE if Dev mode is off
is_minified <- with_devmode(TRUE, {
  get_devmode_option("shiny.minified", TRUE)
})
is_minified # FALSE

Create disk cache (deprecated)

Description

Create disk cache (deprecated)

Usage

diskCache(
  dir = NULL,
  max_size = 500 * 1024^2,
  max_age = Inf,
  max_n = Inf,
  evict = c("lru", "fifo"),
  destroy_on_finalize = FALSE,
  missing = key_missing(),
  exec_missing = deprecated(),
  logfile = NULL
)

Arguments

Reactive domains

Description

Reactive domains are a mechanism for establishing ownership over reactive primitives (like reactive expressions and observers), even if the set of reactive primitives is dynamically created. This is useful for lifetime management (i.e. destroying observers when the Shiny session that created them ends) and error handling.

Usage

getDefaultReactiveDomain()

withReactiveDomain(domain, expr)

onReactiveDomainEnded(domain, callback, failIfNull = FALSE)

Arguments

Details

At any given time, there can be either a single "default" reactive domain object, or none (i.e. the reactive domain object is NULL). You can access the current default reactive domain by calling getDefaultReactiveDomain.

Unless you specify otherwise, newly created observers and reactive expressions will be assigned to the current default domain (if any). You can override this assignment by providing an explicit domain argument to reactive() or observe().

For advanced usage, it's possible to override the default domain using withReactiveDomain. The domain argument will be made the default domain while expr is evaluated.

Implementers of new reactive primitives can use onReactiveDomainEnded as a convenience function for registering callbacks. If the reactive domain is NULL and failIfNull is FALSE, then the callback will never be invoked.

Create a download button or link

Description

Use these functions to create a download button or link; when clicked, it will initiate a browser download. The filename and contents are specified by the corresponding downloadHandler() defined in the server function.

Usage

downloadButton(
  outputId,
  label = "Download",
  class = NULL,
  ...,
  icon = shiny::icon("download")
)

downloadLink(outputId, label = "Download", class = NULL, ...)

Arguments

See Also

downloadHandler()

Examples

## Not run: 
ui <- fluidPage(
  p("Choose a dataset to download."),
  selectInput("dataset", "Dataset", choices = c("mtcars", "airquality")),
  downloadButton("downloadData", "Download")
)

server <- function(input, output) {
  # The requested dataset
  data <- reactive({
    get(input$dataset)
  })

  output$downloadData <- downloadHandler(
    filename = function() {
      # Use the selected dataset as the suggested file name
      paste0(input$dataset, ".csv")
    },
    content = function(file) {
      # Write the dataset to the `file` that will be downloaded
      write.csv(data(), file)
    }
  )
}

shinyApp(ui, server)

## End(Not run)

File Downloads

Description

Allows content from the Shiny application to be made available to the user as file downloads (for example, downloading the currently visible data as a CSV file). Both filename and contents can be calculated dynamically at the time the user initiates the download. Assign the return value to a slot on output in your server function, and in the UI use downloadButton() or downloadLink() to make the download available.

Usage

downloadHandler(filename, content, contentType = NULL, outputArgs = list())

Arguments

Examples

## Only run examples in interactive R sessions
if (interactive()) {

ui <- fluidPage(
  downloadButton("downloadData", "Download")
)

server <- function(input, output) {
  # Our dataset
  data <- mtcars

  output$downloadData <- downloadHandler(
    filename = function() {
      paste("data-", Sys.Date(), ".csv", sep="")
    },
    content = function(file) {
      write.csv(data, file)
    }
  )
}

shinyApp(ui, server)
}

Enable bookmarking for a Shiny application

Description

There are two types of bookmarking: saving an application's state to disk on the server, and encoding the application's state in a URL. For state that has been saved to disk, the state can be restored with the corresponding state ID. For URL-encoded state, the state of the application is encoded in the URL, and no server-side storage is needed.

URL-encoded bookmarking is appropriate for applications where there not many input values that need to be recorded. Some browsers have a length limit for URLs of about 2000 characters, and if there are many inputs, the length of the URL can exceed that limit.

Saved-on-server bookmarking is appropriate when there are many inputs, or when the bookmarked state requires storing files.

Usage

enableBookmarking(store = c("url", "server", "disable"))

Arguments

Details

For restoring state to work properly, the UI must be a function that takes one argument, request. In most Shiny applications, the UI is not a function; it might have the form fluidPage(....). Converting it to a function is as simple as wrapping it in a function, as in function(request) { fluidPage(....) }.

By default, all input values will be bookmarked, except for the values of passwordInputs. fileInputs will be saved if the state is saved on a server, but not if the state is encoded in a URL.

When bookmarking state, arbitrary values can be stored, by passing a function as the onBookmark argument. That function will be passed a ShinySaveState object. The values field of the object is a list which can be manipulated to save extra information. Additionally, if the state is being saved on the server, and the dir field of that object can be used to save extra information to files in that directory.

For saved-to-server state, this is how the state directory is chosen:

• If running in a hosting environment such as Shiny Server or Connect, the hosting environment will choose the directory.

• If running an app in a directory with runApp(), the saved states will be saved in a subdirectory of the app called shiny_bookmarks.

• If running a Shiny app object that is generated from code (not run from a directory), the saved states will be saved in a subdirectory of the current working directory called shiny_bookmarks.

When used with shinyApp(), this function must be called before shinyApp(), or in the shinyApp()'s onStart function. An alternative to calling the enableBookmarking() function is to use the enableBookmarking argument for shinyApp(). See examples below.

See Also

onBookmark(), onBookmarked(), onRestore(), and onRestored() for registering callback functions that are invoked when the state is bookmarked or restored.

Also see updateQueryString().

Examples

## Only run these examples in interactive R sessions
if (interactive()) {

# Basic example with state encoded in URL
ui <- function(request) {
  fluidPage(
    textInput("txt", "Text"),
    checkboxInput("chk", "Checkbox"),
    bookmarkButton()
  )
}
server <- function(input, output, session) { }
enableBookmarking("url")
shinyApp(ui, server)


# An alternative to calling enableBookmarking(): use shinyApp's
# enableBookmarking argument
shinyApp(ui, server, enableBookmarking = "url")


# Same basic example with state saved to disk
enableBookmarking("server")
shinyApp(ui, server)


# Save/restore arbitrary values
ui <- function(req) {
  fluidPage(
    textInput("txt", "Text"),
    checkboxInput("chk", "Checkbox"),
    bookmarkButton(),
    br(),
    textOutput("lastSaved")
  )
}
server <- function(input, output, session) {
  vals <- reactiveValues(savedTime = NULL)
  output$lastSaved <- renderText({
    if (!is.null(vals$savedTime))
      paste("Last saved at", vals$savedTime)
    else
      ""
  })

  onBookmark(function(state) {
    vals$savedTime <- Sys.time()
    # state is a mutable reference object, and we can add arbitrary values
    # to it.
    state$values$time <- vals$savedTime
  })
  onRestore(function(state) {
    vals$savedTime <- state$values$time
  })
}
enableBookmarking(store = "url")
shinyApp(ui, server)


# Usable with dynamic UI (set the slider, then change the text input,
# click the bookmark button)
ui <- function(request) {
  fluidPage(
    sliderInput("slider", "Slider", 1, 100, 50),
    uiOutput("ui"),
    bookmarkButton()
  )
}
server <- function(input, output, session) {
  output$ui <- renderUI({
    textInput("txt", "Text", input$slider)
  })
}
enableBookmarking("url")
shinyApp(ui, server)


# Exclude specific inputs (The only input that will be saved in this
# example is chk)
ui <- function(request) {
  fluidPage(
    passwordInput("pw", "Password"), # Passwords are never saved
    sliderInput("slider", "Slider", 1, 100, 50), # Manually excluded below
    checkboxInput("chk", "Checkbox"),
    bookmarkButton()
  )
}
server <- function(input, output, session) {
  setBookmarkExclude("slider")
}
enableBookmarking("url")
shinyApp(ui, server)


# Update the browser's location bar every time an input changes. This should
# not be used with enableBookmarking("server"), because that would create a
# new saved state on disk every time the user changes an input.
ui <- function(req) {
  fluidPage(
    textInput("txt", "Text"),
    checkboxInput("chk", "Checkbox")
  )
}
server <- function(input, output, session) {
  observe({
    # Trigger this observer every time an input changes
    reactiveValuesToList(input)
    session$doBookmark()
  })
  onBookmarked(function(url) {
    updateQueryString(url)
  })
}
enableBookmarking("url")
shinyApp(ui, server)


# Save/restore uploaded files
ui <- function(request) {
  fluidPage(
    sidebarLayout(
      sidebarPanel(
        fileInput("file1", "Choose CSV File", multiple = TRUE,
          accept = c(
            "text/csv",
            "text/comma-separated-values,text/plain",
            ".csv"
          )
        ),
        tags$hr(),
        checkboxInput("header", "Header", TRUE),
        bookmarkButton()
      ),
      mainPanel(
        tableOutput("contents")
      )
    )
  )
}
server <- function(input, output) {
  output$contents <- renderTable({
    inFile <- input$file1
    if (is.null(inFile))
      return(NULL)

    if (nrow(inFile) == 1) {
      read.csv(inFile$datapath, header = input$header)
    } else {
      data.frame(x = "multiple files")
    }
  })
}
enableBookmarking("server")
shinyApp(ui, server)

}

Register expressions for export in test mode

Description

This function registers expressions that will be evaluated when a test export event occurs. These events are triggered by accessing a snapshot URL.

Usage

exportTestValues(
  ...,
  quoted_ = FALSE,
  env_ = parent.frame(),
  session_ = getDefaultReactiveDomain()
)

Arguments

Details

This function only has an effect if the app is launched in test mode. This is done by calling runApp() with test.mode=TRUE, or by setting the global option shiny.testmode to TRUE.

Examples

## Only run this example in interactive R sessions
if (interactive()) {

options(shiny.testmode = TRUE)

# This application shows the test snapshot URL; clicking on it will
# fetch the input, output, and exported values in JSON format.
shinyApp(
  ui = basicPage(
    h4("Snapshot URL: "),
    uiOutput("url"),
    h4("Current values:"),
    verbatimTextOutput("values"),
    actionButton("inc", "Increment x")
  ),

  server = function(input, output, session) {
    vals <- reactiveValues(x = 1)
    y <- reactive({ vals$x + 1 })

    observeEvent(input$inc, {
      vals$x <<- vals$x + 1
    })

    exportTestValues(
      x = vals$x,
      y = y()
    )

    output$url <- renderUI({
      url <- session$getTestSnapshotUrl(format="json")
      a(href = url, url)
    })

    output$values <- renderText({
      paste0("vals$x: ", vals$x, "\ny: ", y())
    })
  }
)
}

Convert an expression to a function

Description

Please use installExprFunction() for a better debugging experience (Shiny 0.8.0). If the expr and quoted parameters are not needed, please see quoToFunction() (Shiny 1.6.0).

Usage

exprToFunction(expr, env = parent.frame(), quoted = FALSE)

Arguments

Details

Similar to installExprFunction() but doesn't register debug hooks.

See Also

installExprFunction() for the modern approach to converting an expression to a function

Task or computation that proceeds in the background

Description

In normal Shiny reactive code, whenever an observer, calc, or output is busy computing, it blocks the current session from receiving any inputs or attempting to proceed with any other computation related to that session.

The ExtendedTask class allows you to have an expensive operation that is started by a reactive effect, and whose (eventual) results can be accessed by a regular observer, calc, or output; but during the course of the operation, the current session is completely unblocked, allowing the user to continue using the rest of the app while the operation proceeds in the background.

Note that each ExtendedTask object does not represent a single invocation of its long-running function. Rather, it's an object that is used to invoke the function with different arguments, keeps track of whether an invocation is in progress, and provides ways to get at the current status or results of the operation. A single ExtendedTask object does not permit overlapping invocations: if the invoke() method is called before the previous invoke() is completed, the new invocation will not begin until the previous invocation has completed.

ExtendedTask versus asynchronous reactives

Shiny has long supported using {promises} to write asynchronous observers, calcs, or outputs. You may be wondering what the differences are between those techniques and this class.

Asynchronous observers, calcs, and outputs are not–and have never been–designed to let a user start a long-running operation, while keeping that very same (browser) session responsive to other interactions. Instead, they unblock other sessions, so you can take a long-running operation that would normally bring the entire R process to a halt and limit the blocking to just the session that started the operation. (For more details, see the section on "The Flush Cycle".)

ExtendedTask, on the other hand, invokes an asynchronous function (that is, a function that quickly returns a promise) and allows even that very session to immediately unblock and carry on with other user interactions.

Methods

Public methods

• ExtendedTask$new()

• ExtendedTask$invoke()

• ExtendedTask$status()

• ExtendedTask$result()

Method new()

Creates a new ExtendedTask object. ExtendedTask should generally be created either at the top of a server function, or at the top of a module server function.

Usage

ExtendedTask$new(func)

Arguments

Method invoke()

Starts executing the long-running operation. If this ExtendedTask is already running (meaning, a previous call to invoke() is not yet complete) then enqueues this invocation until after the current invocation, and any already-enqueued invocation, completes.

Usage

ExtendedTask$invoke(...)

Arguments

Method status()

This is a reactive read that invalidates the caller when the task's status changes.

Returns one of the following values:

• "initial": This ExtendedTask has not yet been invoked

• "running": An invocation is currently running

• "success": An invocation completed successfully, and a value can be retrieved via the result() method

• "error": An invocation completed with an error, which will be re-thrown if you call the result() method

Usage

ExtendedTask$status()

Method result()

Attempts to read the results of the most recent invocation. This is a reactive read that invalidates as the task's status changes.

The actual behavior differs greatly depending on the current status of the task:

• "initial": Throws a silent error (like req(FALSE)). If this happens during output rendering, the output will be blanked out.

• "running": Throws a special silent error that, if it happens during output rendering, makes the output appear "in progress" until further notice.

• "success": Returns the return value of the most recent invocation.

• "error": Throws whatever error was thrown by the most recent invocation.

This method is intended to be called fairly naively by any output or reactive expression that cares about the output–you just have to be aware that if the result isn't ready for whatever reason, processing will stop in much the same way as req(FALSE) does, but when the result is ready you'll get invalidated, and when you run again the result should be there.

Note that the result() method is generally not meant to be used with observeEvent(), eventReactive(), bindEvent(), or isolate() as the invalidation will be ignored.

Usage

ExtendedTask$result()

Examples

library(shiny)
library(bslib)
library(future)
plan(multisession)

ui <- page_fluid(
  titlePanel("Extended Task Demo"),
  p(
    'Click the button below to perform a "calculation"',
    "that takes a while to perform."
  ),
  input_task_button("recalculate", "Recalculate"),
  p(textOutput("result"))
)

server <- function(input, output) {
  rand_task <- ExtendedTask$new(function() {
    future(
      {
        # Slow operation goes here
        Sys.sleep(2)
        sample(1:100, 1)
      },
      seed = TRUE
    )
  })

  # Make button state reflect task.
  # If using R >=4.1, you can do this instead:
  # rand_task <- ExtendedTask$new(...) |> bind_task_button("recalculate")
  bind_task_button(rand_task, "recalculate")

  observeEvent(input$recalculate, {
    # Invoke the extended in an observer
    rand_task$invoke()
  })

  output$result <- renderText({
    # React to updated results when the task completes
    number <- rand_task$result()
    paste0("Your number is ", number, ".")
  })
}

shinyApp(ui, server)

File Upload Control

Description

Create a file upload control that can be used to upload one or more files.

Usage

fileInput(
  inputId,
  label,
  multiple = FALSE,
  accept = NULL,
  width = NULL,
  buttonLabel = "Browse...",
  placeholder = "No file selected",
  capture = NULL
)

Arguments

Details

Whenever a file upload completes, the corresponding input variable is set to a dataframe. See the ⁠Server value⁠ section.

Each time files are uploaded, they are written to a new random subdirectory inside of R's process-level temporary directory. The Shiny user session keeps track of all uploads in the session, and when the session ends, Shiny deletes all of the subdirectories where files where uploaded to.

Server value

A data.frame that contains one row for each selected file, and following columns:

name

The filename provided by the web browser. This is not the path to read to get at the actual data that was uploaded (see datapath column).

size

The size of the uploaded data, in bytes.

type

The MIME type reported by the browser (for example, text/plain), or empty string if the browser didn't know.

datapath

The path to a temp file that contains the data that was uploaded. This file may be deleted if the user performs another upload operation.

See Also

Other input elements: actionButton(), checkboxGroupInput(), checkboxInput(), dateInput(), dateRangeInput(), numericInput(), passwordInput(), radioButtons(), selectInput(), sliderInput(), submitButton(), textAreaInput(), textInput(), varSelectInput()

Examples

## Only run examples in interactive R sessions
if (interactive()) {

ui <- fluidPage(
  sidebarLayout(
    sidebarPanel(
      fileInput("file1", "Choose CSV File", accept = ".csv"),
      checkboxInput("header", "Header", TRUE)
    ),
    mainPanel(
      tableOutput("contents")
    )
  )
)

server <- function(input, output) {
  output$contents <- renderTable({
    file <- input$file1
    ext <- tools::file_ext(file$datapath)

    req(file)
    validate(need(ext == "csv", "Please upload a csv file"))

    read.csv(file$datapath, header = input$header)
  })
}

shinyApp(ui, server)
}

Create a page that fills the window

Description

fillPage creates a page whose height and width always fill the available area of the browser window.

Usage

fillPage(
  ...,
  padding = 0,
  title = NULL,
  bootstrap = TRUE,
  theme = NULL,
  lang = NULL
)

Arguments

Details

The fluidPage() and fixedPage() functions are used for creating web pages that are laid out from the top down, leaving whitespace at the bottom if the page content's height is smaller than the browser window, and scrolling if the content is larger than the window.

fillPage is designed to latch the document body's size to the size of the window. This makes it possible to fill it with content that also scales to the size of the window.

For example, fluidPage(plotOutput("plot", height = "100%")) will not work as expected; the plot element's effective height will be 0, because the plot's containing elements (⁠<div>⁠ and ⁠<body>⁠) have automatic height; that is, they determine their own height based on the height of their contained elements. However, fillPage(plotOutput("plot", height = "100%")) will work because fillPage fixes the ⁠<body>⁠ height at 100% of the window height.

Note that fillPage(plotOutput("plot")) will not cause the plot to fill the page. Like most Shiny output widgets, plotOutput's default height is a fixed number of pixels. You must explicitly set height = "100%" if you want a plot (or htmlwidget, say) to fill its container.

One must be careful what layouts/panels/elements come between the fillPage and the plots/widgets. Any container that has an automatic height will cause children with height = "100%" to misbehave. Stick to functions that are designed for fill layouts, such as the ones in this package.

See Also

Other layout functions: fixedPage(), flowLayout(), fluidPage(), navbarPage(), sidebarLayout(), splitLayout(), verticalLayout()

Examples

fillPage(
  tags$style(type = "text/css",
    ".half-fill { width: 50%; height: 100%; }",
    "#one { float: left; background-color: #ddddff; }",
    "#two { float: right; background-color: #ccffcc; }"
  ),
  div(id = "one", class = "half-fill",
    "Left half"
  ),
  div(id = "two", class = "half-fill",
    "Right half"
  ),
  padding = 10
)

fillPage(
  fillRow(
    div(style = "background-color: red; width: 100%; height: 100%;"),
    div(style = "background-color: blue; width: 100%; height: 100%;")
  )
)

Flex Box-based row/column layouts

Description

Creates row and column layouts with proportionally-sized cells, using the Flex Box layout model of CSS3. These can be nested to create arbitrary proportional-grid layouts. Warning: Flex Box is not well supported by Internet Explorer, so these functions should only be used where modern browsers can be assumed.

Usage

fillRow(..., flex = 1, width = "100%", height = "100%")

fillCol(..., flex = 1, width = "100%", height = "100%")

Arguments

Details

If you try to use fillRow and fillCol inside of other Shiny containers, such as sidebarLayout(), navbarPage(), or even tags$div, you will probably find that they will not appear. This is due to fillRow and fillCol defaulting to height="100%", which will only work inside of containers that have determined their own size (rather than shrinking to the size of their contents, as is usually the case in HTML).

To avoid this problem, you have two options:

• only use fillRow/fillCol inside of fillPage, fillRow, or fillCol

• provide an explicit height argument to fillRow/fillCol

Examples

# Only run this example in interactive R sessions.
if (interactive()) {

ui <- fillPage(fillRow(
  plotOutput("plotLeft", height = "100%"),
  fillCol(
    plotOutput("plotTopRight", height = "100%"),
    plotOutput("plotBottomRight", height = "100%")
  )
))

server <- function(input, output, session) {
  output$plotLeft <- renderPlot(plot(cars))
  output$plotTopRight <- renderPlot(plot(pressure))
  output$plotBottomRight <- renderPlot(plot(AirPassengers))
}

shinyApp(ui, server)

}

Create a page with a fixed layout

Description

Functions for creating fixed page layouts. A fixed page layout consists of rows which in turn include columns. Rows exist for the purpose of making sure their elements appear on the same line (if the browser has adequate width). Columns exist for the purpose of defining how much horizontal space within a 12-unit wide grid it's elements should occupy. Fixed pages limit their width to 940 pixels on a typical display, and 724px or 1170px on smaller and larger displays respectively.

Usage

fixedPage(..., title = NULL, theme = NULL, lang = NULL)

fixedRow(...)

Arguments

Details

To create a fixed page use the fixedPage function and include instances of fixedRow and column() within it. Note that unlike fluidPage(), fixed pages cannot make use of higher-level layout functions like sidebarLayout, rather, all layout must be done with fixedRow and column.

Value

A UI definition that can be passed to the shinyUI function.

Note

See the Shiny Application Layout Guide for additional details on laying out fixed pages.

See Also

column()

Other layout functions: fillPage(), flowLayout(), fluidPage(), navbarPage(), sidebarLayout(), splitLayout(), verticalLayout()

Examples

## Only run examples in interactive R sessions
if (interactive()) {

ui <- fixedPage(
  title = "Hello, Shiny!",
  fixedRow(
    column(width = 4,
      "4"
    ),
    column(width = 3, offset = 2,
      "3 offset 2"
    )
  )
)

shinyApp(ui, server = function(input, output) { })
}

Flow layout

Description

Lays out elements in a left-to-right, top-to-bottom arrangement. The elements on a given row will be top-aligned with each other. This layout will not work well with elements that have a percentage-based width (e.g. plotOutput() at its default setting of width = "100%").

Usage

flowLayout(..., cellArgs = list())

Arguments

See Also

Other layout functions: fillPage(), fixedPage(), fluidPage(), navbarPage(), sidebarLayout(), splitLayout(), verticalLayout()

Examples

## Only run examples in interactive R sessions
if (interactive()) {

ui <- flowLayout(
  numericInput("rows", "How many rows?", 5),
  selectInput("letter", "Which letter?", LETTERS),
  sliderInput("value", "What value?", 0, 100, 50)
)
shinyApp(ui, server = function(input, output) { })
}

Create a page with fluid layout

Description

Functions for creating fluid page layouts. A fluid page layout consists of rows which in turn include columns. Rows exist for the purpose of making sure their elements appear on the same line (if the browser has adequate width). Columns exist for the purpose of defining how much horizontal space within a 12-unit wide grid it's elements should occupy. Fluid pages scale their components in realtime to fill all available browser width.

Usage

fluidPage(..., title = NULL, theme = NULL, lang = NULL)

fluidRow(...)

Arguments

Details

To create a fluid page use the fluidPage function and include instances of fluidRow and column() within it. As an alternative to low-level row and column functions you can also use higher-level layout functions like sidebarLayout().

Value

A UI definition that can be passed to the shinyUI function.

Note

See the Shiny-Application-Layout-Guide for additional details on laying out fluid pages.

See Also

column()

Other layout functions: fillPage(), fixedPage(), flowLayout(), navbarPage(), sidebarLayout(), splitLayout(), verticalLayout()

Examples

## Only run examples in interactive R sessions
if (interactive()) {

# Example of UI with fluidPage
ui <- fluidPage(

  # Application title
  titlePanel("Hello Shiny!"),

  sidebarLayout(

    # Sidebar with a slider input
    sidebarPanel(
      sliderInput("obs",
                  "Number of observations:",
                  min = 0,
                  max = 1000,
                  value = 500)
    ),

    # Show a plot of the generated distribution
    mainPanel(
      plotOutput("distPlot")
    )
  )
)

# Server logic
server <- function(input, output) {
  output$distPlot <- renderPlot({
    hist(rnorm(input$obs))
  })
}

# Complete app with UI and server components
shinyApp(ui, server)


# UI demonstrating column layouts
ui <- fluidPage(
  title = "Hello Shiny!",
  fluidRow(
    column(width = 4,
      "4"
    ),
    column(width = 3, offset = 2,
      "3 offset 2"
    )
  )
)

shinyApp(ui, server = function(input, output) { })
}

Freeze a reactive value

Description

These functions freeze a reactiveVal(), or an element of a reactiveValues(). If the value is accessed while frozen, a "silent" exception is raised and the operation is stopped. This is the same thing that happens if req(FALSE) is called. The value is thawed (un-frozen; accessing it will no longer raise an exception) when the current reactive domain is flushed. In a Shiny application, this occurs after all of the observers are executed. NOTE: We are considering deprecating freezeReactiveVal, and freezeReactiveValue except when x is input. If this affects your app, please let us know by leaving a comment on this GitHub issue.

Usage

freezeReactiveVal(x)

freezeReactiveValue(x, name)

Arguments

See Also

req()

Examples

## Only run this examples in interactive R sessions
if (interactive()) {

ui <- fluidPage(
  selectInput("data", "Data Set", c("mtcars", "pressure")),
  checkboxGroupInput("cols", "Columns (select 2)", character(0)),
  plotOutput("plot")
)

server <- function(input, output, session) {
  observe({
    data <- get(input$data)
    # Sets a flag on input$cols to essentially do req(FALSE) if input$cols
    # is accessed. Without this, an error will momentarily show whenever a
    # new data set is selected.
    freezeReactiveValue(input, "cols")
    updateCheckboxGroupInput(session, "cols", choices = names(data))
  })

  output$plot <- renderPlot({
    # When a new data set is selected, input$cols will have been invalidated
    # above, and this will essentially do the same as req(FALSE), causing
    # this observer to stop and raise a silent exception.
    cols <- input$cols
    data <- get(input$data)

    if (length(cols) == 2) {
      plot(data[[ cols[1] ]], data[[ cols[2] ]])
    }
  })
}

shinyApp(ui, server)
}

Get output information

Description

Returns information about the currently executing output, including its name (i.e., outputId); and in some cases, relevant sizing and styling information.

Usage

getCurrentOutputInfo(session = getDefaultReactiveDomain())

Arguments

Value

NULL if called outside of an output context; otherwise, a list which includes:

• The name of the output (reported for any output).

• If the output is a plotOutput() or imageOutput(), then:

  • height: a reactive expression which returns the height in pixels.

  • width: a reactive expression which returns the width in pixels.

• If the output is a plotOutput(), imageOutput(), or contains a shiny-report-theme class, then:

  • bg: a reactive expression which returns the background color.

  • fg: a reactive expression which returns the foreground color.

  • accent: a reactive expression which returns the hyperlink color.

  • font: a reactive expression which returns a list of font information, including:

    • families: a character vector containing the CSS font-family property.

    • size: a character string containing the CSS font-size property

Examples

if (interactive()) {
  shinyApp(
    fluidPage(
      tags$style(HTML("body {background-color: black; color: white; }")),
      tags$style(HTML("body a {color: purple}")),
      tags$style(HTML("#info {background-color: teal; color: orange; }")),
      plotOutput("p"),
      "Computed CSS styles for the output named info:",
      tagAppendAttributes(
        textOutput("info"),
        class = "shiny-report-theme"
      )
    ),
    function(input, output) {
      output$p <- renderPlot({
        info <- getCurrentOutputInfo()
        par(bg = info$bg(), fg = info$fg(), col.axis = info$fg(), col.main = info$fg())
        plot(1:10, col = info$accent(), pch = 19)
        title("A simple R plot that uses its CSS styling")
      })
      output$info <- renderText({
        info <- getCurrentOutputInfo()
        jsonlite::toJSON(
          list(
            bg = info$bg(),
            fg = info$fg(),
            accent = info$accent(),
            font = info$font()
          ),
          auto_unbox = TRUE
        )
      })
    }
  )
}

Obtain Shiny's Bootstrap Sass theme

Description

Intended for use by Shiny developers to create Shiny bindings with intelligent styling based on the bootstrapLib()'s theme value.

Usage

getCurrentTheme()

Value

If called at render-time (i.e., inside a htmltools::tagFunction()), and bootstrapLib()'s theme has been set to a bslib::bs_theme() object, then this returns the theme. Otherwise, this returns NULL.

See Also

getCurrentOutputInfo(), bootstrapLib(), htmltools::tagFunction()

Get the query string / hash component from the URL

Description

Two user friendly wrappers for getting the query string and the hash component from the app's URL.

Usage

getQueryString(session = getDefaultReactiveDomain())

getUrlHash(session = getDefaultReactiveDomain())

Arguments

Details

These can be particularly useful if you want to display different content depending on the values in the query string / hash (e.g. instead of basing the conditional on an input or a calculated reactive, you can base it on the query string). However, note that, if you're changing the query string / hash programmatically from within the server code, you must use ⁠updateQueryString(_yourNewQueryString_, mode = "push")⁠. The default mode for updateQueryString is "replace", which doesn't raise any events, so any observers or reactives that depend on it will not get triggered. However, if you're changing the query string / hash directly by typing directly in the browser and hitting enter, you don't have to worry about this.

Value

For getQueryString, a named list. For example, the query string ?param1=value1&param2=value2 becomes list(param1 = value1, param2 = value2). For getUrlHash, a character vector with the hash (including the leading ⁠#⁠ symbol).

See Also

updateQueryString()

Examples

## Only run this example in interactive R sessions
if (interactive()) {

  ## App 1: getQueryString
  ## Printing the value of the query string
  ## (Use the back and forward buttons to see how the browser
  ## keeps a record of each state)
  shinyApp(
    ui = fluidPage(
      textInput("txt", "Enter new query string"),
      helpText("Format: ?param1=val1&param2=val2"),
      actionButton("go", "Update"),
      hr(),
      verbatimTextOutput("query")
    ),
    server = function(input, output, session) {
      observeEvent(input$go, {
        updateQueryString(input$txt, mode = "push")
      })
      output$query <- renderText({
        query <- getQueryString()
        queryText <- paste(names(query), query,
                       sep = "=", collapse=", ")
        paste("Your query string is:\n", queryText)
      })
    }
  )

  ## App 2: getUrlHash
  ## Printing the value of the URL hash
  ## (Use the back and forward buttons to see how the browser
  ## keeps a record of each state)
  shinyApp(
    ui = fluidPage(
      textInput("txt", "Enter new hash"),
      helpText("Format: #hash"),
      actionButton("go", "Update"),
      hr(),
      verbatimTextOutput("hash")
    ),
    server = function(input, output, session) {
      observeEvent(input$go, {
        updateQueryString(input$txt, mode = "push")
      })
      output$hash <- renderText({
        hash <- getUrlHash()
        paste("Your hash is:\n", hash)
      })
    }
  )
}

Get or set Shiny options

Description

There are two mechanisms for working with options for Shiny. One is the options() function, which is part of base R, and the other is the shinyOptions() function, which is in the Shiny package. The reason for these two mechanisms is has to do with legacy code and scoping.

The options() function sets options globally, for the duration of the R process. The getOption() function retrieves the value of an option. All shiny related options of this type are prefixed with "shiny.".

The shinyOptions() function sets the value of a shiny option, but unlike options(), it is not always global in scope; the options may be scoped globally, to an application, or to a user session in an application, depending on the context. The getShinyOption() function retrieves a value of a shiny option. Currently, the options set via shinyOptions are for internal use only.

Usage

getShinyOption(name, default = NULL)

shinyOptions(...)

Arguments

Options with options()

shiny.autoreload (defaults to FALSE)

If TRUE when a Shiny app is launched, the app directory will be continually monitored for changes to files that have the extensions: r, htm, html, js, css, png, jpg, jpeg, gif. If any changes are detected, all connected Shiny sessions are reloaded. This allows for fast feedback loops when tweaking Shiny UI.

Since monitoring for changes is expensive (we simply poll for last modified times), this feature is intended only for development.

You can customize the file patterns Shiny will monitor by setting the shiny.autoreload.pattern option. For example, to monitor only ui.R: options(shiny.autoreload.pattern = glob2rx("ui.R"))

The default polling interval is 500 milliseconds. You can change this by setting e.g. options(shiny.autoreload.interval = 2000) (every two seconds).

shiny.deprecation.messages (defaults to TRUE)

This controls whether messages for deprecated functions in Shiny will be printed. See shinyDeprecated() for more information.

shiny.error (defaults to NULL)

This can be a function which is called when an error occurs. For example, options(shiny.error=recover) will result a the debugger prompt when an error occurs.

shiny.fullstacktrace (defaults to FALSE)

Controls whether "pretty" (FALSE) or full stack traces (TRUE) are dumped to the console when errors occur during Shiny app execution. Pretty stack traces attempt to only show user-supplied code, but this pruning can't always be done 100% correctly.

shiny.host (defaults to "127.0.0.1")

The IP address that Shiny should listen on. See runApp() for more information.

shiny.jquery.version (defaults to 3)

The major version of jQuery to use. Currently only values of 3 or 1 are supported. If 1, then jQuery 1.12.4 is used. If 3, then jQuery 3.6.0 is used.

shiny.json.digits (defaults to I(16))

Max number of digits to use when converting numbers to JSON format to send to the client web browser. Use I() to specify significant digits. Use NA for max precision.

shiny.launch.browser (defaults to interactive())

A boolean which controls the default behavior when an app is run. See runApp() for more information.

shiny.mathjax.url (defaults to "https://mathjax.rstudio.com/latest/MathJax.js")

The URL that should be used to load MathJax, via withMathJax().

shiny.mathjax.config (defaults to "config=TeX-AMS-MML_HTMLorMML")

The querystring used to load MathJax, via withMathJax().

shiny.maxRequestSize (defaults to 5MB)

This is a number which specifies the maximum web request size, which serves as a size limit for file uploads.

shiny.minified (defaults to TRUE)

By default Whether or not to include Shiny's JavaScript as a minified (shiny.min.js) or un-minified (shiny.js) file. The un-minified version is larger, but can be helpful for development and debugging.

shiny.port (defaults to a random open port)

A port number that Shiny will listen on. See runApp() for more information.

shiny.reactlog (defaults to FALSE)

If TRUE, enable logging of reactive events, which can be viewed later with the reactlogShow() function. This incurs a substantial performance penalty and should not be used in production.

shiny.sanitize.errors (defaults to FALSE)

If TRUE, then normal errors (i.e. errors not wrapped in safeError) won't show up in the app; a simple generic error message is printed instead (the error and stack trace printed to the console remain unchanged). If you want to sanitize errors in general, but you DO want a particular error e to get displayed to the user, then set this option to TRUE and use stop(safeError(e)) for errors you want the user to see.

shiny.stacktraceoffset (defaults to TRUE)

If TRUE, then Shiny's printed stack traces will display srcrefs one line above their usual location. This is an arguably more intuitive arrangement for casual R users, as the name of a function appears next to the srcref where it is defined, rather than where it is currently being called from.

shiny.suppressMissingContextError (defaults to FALSE)

Normally, invoking a reactive outside of a reactive context (or isolate()) results in an error. If this is TRUE, don't error in these cases. This should only be used for debugging or demonstrations of reactivity at the console.

shiny.testmode (defaults to FALSE)

If TRUE, then various features for testing Shiny applications are enabled.

shiny.snapshotsortc (defaults to FALSE)

If TRUE, test snapshot keys for shinytest will be sorted consistently using the C locale. Snapshots retrieved by shinytest2 will always sort using the C locale.

shiny.trace (defaults to FALSE)

Print messages sent between the R server and the web browser client to the R console. This is useful for debugging. Possible values are "send" (only print messages sent to the client), "recv" (only print messages received by the server), TRUE (print all messages), or FALSE (default; don't print any of these messages).

shiny.autoload.r (defaults to TRUE)

If TRUE, then the R/ of a shiny app will automatically be sourced.

shiny.useragg (defaults to TRUE)

Set to FALSE to prevent PNG rendering via the ragg package. See plotPNG() for more information.

shiny.usecairo (defaults to TRUE)

Set to FALSE to prevent PNG rendering via the Cairo package. See plotPNG() for more information.

shiny.devmode (defaults to NULL)

Option to enable Shiny Developer Mode. When set, different default getOption(key) values will be returned. See devmode() for more details.

Scoping for shinyOptions()

There are three levels of scoping for shinyOptions(): global, application, and session.

The global option set is available by default. Any calls to shinyOptions() and getShinyOption() outside of an app will access the global option set.

When a Shiny application is run with runApp(), the global option set is duplicated and the new option set is available at the application level. If options are set from global.R, app.R, ui.R, or server.R (but outside of the server function), then the application-level options will be modified.

Each time a user session is started, the application-level option set is duplicated, for that session. If the options are set from inside the server function, then they will be scoped to the session.

Options with shinyOptions()

There are a number of global options that affect Shiny's behavior. These can be set globally with options() or locally (for a single app) with shinyOptions().

cache

A caching object that will be used by renderCachedPlot(). If not specified, a cachem::cache_mem() will be used.

Create a header panel

Description

DEPRECATED: use titlePanel() instead.

Usage

headerPanel(title, windowTitle = title)

Arguments

Value

A headerPanel that can be passed to pageWithSidebar

Create a help text element

Description

Create help text which can be added to an input form to provide additional explanation or context.

Usage

helpText(...)

Arguments

Value

A help text element that can be added to a UI definition.

Examples

helpText("Note: while the data view will show only",
         "the specified number of observations, the",
         "summary will be based on the full dataset.")

Create an HTML output element

Description

Render a reactive output variable as HTML within an application page. The text will be included within an HTML div tag, and is presumed to contain HTML content which should not be escaped.

Usage

htmlOutput(
  outputId,
  inline = FALSE,
  container = if (inline) span else div,
  fill = FALSE,
  ...
)

uiOutput(
  outputId,
  inline = FALSE,
  container = if (inline) span else div,
  fill = FALSE,
  ...
)

Arguments

Details

uiOutput is intended to be used with renderUI on the server side. It is currently just an alias for htmlOutput.

Value

An HTML output element that can be included in a panel

Examples

htmlOutput("summary")

# Using a custom container and class
tags$ul(
  htmlOutput("summary", container = tags$li, class = "custom-li-output")
)

Create an HTTP response object

Description

Create an HTTP response object

Usage

httpResponse(
  status = 200L,
  content_type = "text/html; charset=UTF-8",
  content = "",
  headers = list()
)

Arguments

Examples

httpResponse(status = 405L,
  content_type = "text/plain",
  content = "The requested method was not allowed"
)

Create an icon

Description

Create an icon for use within a page. Icons can appear on their own, inside of a button, and/or used with tabPanel() and navbarMenu().

Usage

icon(name, class = NULL, lib = "font-awesome", ...)

Arguments

Value

An ⁠<i>⁠ (icon) HTML tag.

See Also

For lists of available icons, see https://fontawesome.com/icons and https://getbootstrap.com/docs/3.3/components/#glyphicons

Examples

# add an icon to a submit button
submitButton("Update View", icon = icon("redo"))

navbarPage("App Title",
  tabPanel("Plot", icon = icon("bar-chart-o")),
  tabPanel("Summary", icon = icon("list-alt")),
  tabPanel("Table", icon = icon("table"))
)

Input panel

Description

A flowLayout() with a grey border and light grey background, suitable for wrapping inputs.

Usage

inputPanel(...)

Arguments

Dynamically insert/remove a tabPanel

Description

Dynamically insert or remove a tabPanel() (or a navbarMenu()) from an existing tabsetPanel(), navlistPanel() or navbarPage().

Usage

insertTab(
  inputId,
  tab,
  target = NULL,
  position = c("after", "before"),
  select = FALSE,
  session = getDefaultReactiveDomain()
)

prependTab(
  inputId,
  tab,
  select = FALSE,
  menuName = NULL,
  session = getDefaultReactiveDomain()
)

appendTab(
  inputId,
  tab,
  select = FALSE,
  menuName = NULL,
  session = getDefaultReactiveDomain()
)

removeTab(inputId, target, session = getDefaultReactiveDomain())

Arguments

Details

When you want to insert a new tab before or after an existing tab, you should use insertTab. When you want to prepend a tab (i.e. add a tab to the beginning of the tabsetPanel), use prependTab. When you want to append a tab (i.e. add a tab to the end of the tabsetPanel), use appendTab.

For navbarPage, you can insert/remove conventional tabPanels (whether at the top level or nested inside a navbarMenu), as well as an entire navbarMenu(). For the latter case, target should be the menuName that you gave your navbarMenu when you first created it (by default, this is equal to the value of the title argument).

See Also

showTab()

Examples

## Only run this example in interactive R sessions
if (interactive()) {

# example app for inserting/removing a tab
ui <- fluidPage(
  sidebarLayout(
    sidebarPanel(
      actionButton("add", "Add 'Dynamic' tab"),
      actionButton("remove", "Remove 'Foo' tab")
    ),
    mainPanel(
      tabsetPanel(id = "tabs",
        tabPanel("Hello", "This is the hello tab"),
        tabPanel("Foo", "This is the foo tab"),
        tabPanel("Bar", "This is the bar tab")
      )
    )
  )
)
server <- function(input, output, session) {
  observeEvent(input$add, {
    insertTab(inputId = "tabs",
      tabPanel("Dynamic", "This a dynamically-added tab"),
      target = "Bar"
    )
  })
  observeEvent(input$remove, {
    removeTab(inputId = "tabs", target = "Foo")
  })
}

shinyApp(ui, server)


# example app for prepending/appending a navbarMenu
ui <- navbarPage("Navbar page", id = "tabs",
  tabPanel("Home",
    actionButton("prepend", "Prepend a navbarMenu"),
    actionButton("append", "Append a navbarMenu")
  )
)
server <- function(input, output, session) {
  observeEvent(input$prepend, {
    id <- paste0("Dropdown", input$prepend, "p")
    prependTab(inputId = "tabs",
      navbarMenu(id,
        tabPanel("Drop1", paste("Drop1 page from", id)),
        tabPanel("Drop2", paste("Drop2 page from", id)),
        "------",
        "Header",
        tabPanel("Drop3", paste("Drop3 page from", id))
      )
    )
  })
  observeEvent(input$append, {
    id <- paste0("Dropdown", input$append, "a")
    appendTab(inputId = "tabs",
      navbarMenu(id,
        tabPanel("Drop1", paste("Drop1 page from", id)),
        tabPanel("Drop2", paste("Drop2 page from", id)),
        "------",
        "Header",
        tabPanel("Drop3", paste("Drop3 page from", id))
      )
    )
  })
}

shinyApp(ui, server)

}

Insert and remove UI objects

Description

These functions allow you to dynamically add and remove arbitrary UI into your app, whenever you want, as many times as you want. Unlike renderUI(), the UI generated with insertUI() is persistent: once it's created, it stays there until removed by removeUI(). Each new call to insertUI() creates more UI objects, in addition to the ones already there (all independent from one another). To update a part of the UI (ex: an input object), you must use the appropriate render function or a customized reactive function.

Usage

insertUI(
  selector,
  where = c("beforeBegin", "afterBegin", "beforeEnd", "afterEnd"),
  ui,
  multiple = FALSE,
  immediate = FALSE,
  session = getDefaultReactiveDomain()
)

removeUI(
  selector,
  multiple = FALSE,
  immediate = FALSE,
  session = getDefaultReactiveDomain()
)

Arguments

Details

It's particularly useful to pair removeUI with insertUI(), but there is no restriction on what you can use it on. Any element that can be selected through a jQuery selector can be removed through this function.

Examples

## Only run this example in interactive R sessions
if (interactive()) {
# Define UI
ui <- fluidPage(
  actionButton("add", "Add UI")
)

# Server logic
server <- function(input, output, session) {
  observeEvent(input$add, {
    insertUI(
      selector = "#add",
      where = "afterEnd",
      ui = textInput(paste0("txt", input$add),
                     "Insert some text")
    )
  })
}

# Complete app with UI and server components
shinyApp(ui, server)
}

if (interactive()) {
# Define UI
ui <- fluidPage(
  actionButton("rmv", "Remove UI"),
  textInput("txt", "This is no longer useful")
)

# Server logic
server <- function(input, output, session) {
  observeEvent(input$rmv, {
    removeUI(
      selector = "div:has(> #txt)"
    )
  })
}

# Complete app with UI and server components
shinyApp(ui, server)
}

Scheduled Invalidation

Description

Schedules the current reactive context to be invalidated in the given number of milliseconds.

Usage

invalidateLater(millis, session = getDefaultReactiveDomain())

Arguments

Details

If this is placed within an observer or reactive expression, that object will be invalidated (and re-execute) after the interval has passed. The re-execution will reset the invalidation flag, so in a typical use case, the object will keep re-executing and waiting for the specified interval. It's possible to stop this cycle by adding conditional logic that prevents the invalidateLater from being run.

See Also

reactiveTimer() is a slightly less safe alternative.

Examples

## Only run examples in interactive R sessions
if (interactive()) {

ui <- fluidPage(
  sliderInput("n", "Number of observations", 2, 1000, 500),
  plotOutput("plot")
)

server <- function(input, output, session) {

  observe({
    # Re-execute this reactive expression after 1000 milliseconds
    invalidateLater(1000, session)

    # Do something each time this is invalidated.
    # The isolate() makes this observer _not_ get invalidated and re-executed
    # when input$n changes.
    print(paste("The value of input$n is", isolate(input$n)))
  })

  # Generate a new histogram at timed intervals, but not when
  # input$n changes.
  output$plot <- renderPlot({
    # Re-execute this reactive expression after 2000 milliseconds
    invalidateLater(2000)
    hist(rnorm(isolate(input$n)))
  })
}

shinyApp(ui, server)
}

Checks whether an object is a reactivevalues object

Description

Checks whether its argument is a reactivevalues object.

Usage

is.reactivevalues(x)

Arguments

See Also

reactiveValues().

Create a non-reactive scope for an expression

Description

Executes the given expression in a scope where reactive values or expression can be read, but they cannot cause the reactive scope of the caller to be re-evaluated when they change.

Usage

isolate(expr)

Arguments

Details

Ordinarily, the simple act of reading a reactive value causes a relationship to be established between the caller and the reactive value, where a change to the reactive value will cause the caller to re-execute. (The same applies for the act of getting a reactive expression's value.) The isolate function lets you read a reactive value or expression without establishing this relationship.

The expression given to isolate() is evaluated in the calling environment. This means that if you assign a variable inside the isolate(), its value will be visible outside of the isolate(). If you want to avoid this, you can use base::local() inside the isolate().

This function can also be useful for calling reactive expression at the console, which can be useful for debugging. To do so, simply wrap the calls to the reactive expression with isolate().

Examples

## Not run: 
observe({
  input$saveButton  # Do take a dependency on input$saveButton

  # isolate a simple expression
  data <- get(isolate(input$dataset))  # No dependency on input$dataset
  writeToDatabase(data)
})

observe({
  input$saveButton  # Do take a dependency on input$saveButton

  # isolate a whole block
  data <- isolate({
    a <- input$valueA   # No dependency on input$valueA or input$valueB
    b <- input$valueB
    c(a=a, b=b)
  })
  writeToDatabase(data)
})

observe({
  x <- 1
  # x outside of isolate() is affected
  isolate(x <- 2)
  print(x) # 2

  y <- 1
  # Use local() to avoid affecting calling environment
  isolate(local(y <- 2))
  print(y) # 1
})


## End(Not run)

# Can also use isolate to call reactive expressions from the R console
values <- reactiveValues(A=1)
fun <- reactive({ as.character(values$A) })
isolate(fun())
# "1"

# isolate also works if the reactive expression accesses values from the
# input object, like input$x

Check whether a Shiny application is running

Description

This function tests whether a Shiny application is currently running.

Usage

isRunning()

Value

TRUE if a Shiny application is currently running. Otherwise, FALSE.

Truthy and falsy values

Description

The terms "truthy" and "falsy" generally indicate whether a value, when coerced to a base::logical(), is TRUE or FALSE. We use the term a little loosely here; our usage tries to match the intuitive notions of "Is this value missing or available?", or "Has the user provided an answer?", or in the case of action buttons, "Has the button been clicked?".

Usage

isTruthy(x)

Arguments

Details

For example, a textInput that has not been filled out by the user has a value of "", so that is considered a falsy value.

To be precise, a value is truthy unless it is one of:

• FALSE

• NULL

• ""

• An empty atomic vector

• An atomic vector that contains only missing values

• A logical vector that contains all FALSE or missing values

• An object of class "try-error"

• A value that represents an unclicked actionButton()

Note in particular that the value 0 is considered truthy, even though as.logical(0) is FALSE.

Knitr S3 methods

Description

These S3 methods are necessary to help Shiny applications and UI chunks embed themselves in knitr/rmarkdown documents.

Usage

knit_print.shiny.appobj(x, ...)

knit_print.shiny.render.function(x, ..., inline = FALSE)

knit_print.reactive(x, ..., inline = FALSE)

Arguments

Load an app's supporting R files

Description

Loads all of the supporting R files of a Shiny application. Specifically, this function loads any top-level supporting .R files in the ⁠R/⁠ directory adjacent to the app.R/server.R/ui.R files.

Usage

loadSupport(
  appDir = NULL,
  renv = new.env(parent = globalenv()),
  globalrenv = globalenv()
)

Arguments

Details

Since Shiny 1.5.0, this function is called by default when running an application. If it causes problems, there are two ways to opt out. You can either place a file named ⁠_disable_autoload.R⁠ in your R/ directory, or set options(shiny.autoload.r=FALSE). If you set this option, it will affect any application that runs later in the same R session, potentially breaking it, so after running your application, you should unset option with options(shiny.autoload.r=NULL)

The files are sourced in alphabetical order (as determined by list.files). global.R is evaluated before the supporting R files in the ⁠R/⁠ directory.

Make a reactive variable

Description

Turns a normal variable into a reactive variable, that is, one that has reactive semantics when assigned or read in the usual ways. The variable may already exist; if so, its value will be used as the initial value of the reactive variable (or NULL if the variable did not exist).

Usage

makeReactiveBinding(symbol, env = parent.frame())

Arguments

Value

None.

Examples

reactiveConsole(TRUE)

a <- 10
makeReactiveBinding("a")

b <- reactive(a * -1)
observe(print(b()))

a <- 20
a <- 30

reactiveConsole(FALSE)

Insert inline Markdown

Description

This function accepts Markdown-syntax text and returns HTML that may be included in Shiny UIs.

Usage

markdown(mds, extensions = TRUE, .noWS = NULL, ...)

Arguments

Details

Leading whitespace is trimmed from Markdown text with glue::trim(). Whitespace trimming ensures Markdown is processed correctly even when the call to markdown() is indented within surrounding R code.

By default, Github extensions are enabled, but this can be disabled by passing extensions = FALSE.

Markdown rendering is performed by commonmark::markdown_html(). Additional arguments to markdown() are passed as arguments to markdown_html()

Value

a character vector marked as HTML.

Examples

ui <- fluidPage(
  markdown("
    # Markdown Example

    This is a markdown paragraph, and will be contained within a `<p>` tag
    in the UI.

    The following is an unordered list, which will be represented in the UI as
    a `<ul>` with `<li>` children:

    * a bullet
    * another

    [Links](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) work;
    so does *emphasis*.

    To see more of what's possible, check out [commonmark.org/help](https://commonmark.org/help).
    ")
)

Mark a render function with attributes that will be used by the output

Description

Mark a render function with attributes that will be used by the output

Usage

markOutputAttrs(renderFunc, snapshotExclude = NULL, snapshotPreprocess = NULL)

Arguments

Mark a function as a render function

Description

Please use createRenderFunction() to support async execution. (Shiny 1.1.0)

Usage

markRenderFunction(
  uiFunc,
  renderFunc,
  outputArgs = list(),
  cacheHint = "auto",
  cacheWriteHook = NULL,
  cacheReadHook = NULL
)

Arguments

Details

Should be called by implementers of renderXXX functions in order to mark their return values as Shiny render functions, and to provide a hint to Shiny regarding what UI function is most commonly used with this type of render function. This can be used in R Markdown documents to create complete output widgets out of just the render function.

Note that it is generally preferable to use createRenderFunction() instead of markRenderFunction(). It essentially wraps up the user-provided expression in the transform function passed to it, then passes the resulting function to markRenderFunction(). It also provides a simpler calling interface. There may be cases where markRenderFunction() must be used instead of createRenderFunction() – for example, when the transform parameter of createRenderFunction() is not flexible enough for your needs.

Value

The renderFunc function, with annotations.

See Also

createRenderFunction()

Evaluate an expression without a reactive context

Description

Temporarily blocks the current reactive context and evaluates the given expression. Any attempt to directly access reactive values or expressions in expr will give the same results as doing it at the top-level (by default, an error).

Usage

maskReactiveContext(expr)

Arguments

Value

The value of expr.

See Also

isolate()

Create memory cache (deprecated)

Description

Create memory cache (deprecated)

Usage

memoryCache(
  max_size = 200 * 1024^2,
  max_age = Inf,
  max_n = Inf,
  evict = c("lru", "fifo"),
  missing = key_missing(),
  exec_missing = deprecated(),
  logfile = NULL
)

Arguments

Mock Shiny Session

Description

An R6 class suitable for testing purposes. Simulates, to the extent possible, the behavior of the ShinySession class. The session parameter provided to Shiny server functions and modules is an instance of a ShinySession in normal operation.

Most kinds of module and server testing do not require this class be instantiated manually. See instead testServer().

In order to support advanced usage, instances of MockShinySession are unlocked so that public methods and fields of instances may be modified. For example, in order to test authentication workflows, the user or groups fields may be overridden. Modified instances of MockShinySession may then be passed explicitly as the session argument of testServer().

Public fields

Active bindings

Methods

Public methods

• MockShinySession$new()

• MockShinySession$onFlush()

• MockShinySession$onFlushed()

• MockShinySession$onEnded()

• MockShinySession$isEnded()

• MockShinySession$isClosed()

• MockShinySession$close()

• MockShinySession$cycleStartAction()

• MockShinySession$fileUrl()

• MockShinySession$setInputs()

• MockShinySession$.scheduleTask()

• MockShinySession$elapse()

• MockShinySession$.now()

• MockShinySession$defineOutput()

• MockShinySession$getOutput()

• MockShinySession$ns()

• MockShinySession$flushReact()

• MockShinySession$makeScope()

• MockShinySession$setEnv()

• MockShinySession$setReturned()

• MockShinySession$getReturned()

• MockShinySession$genId()

• MockShinySession$rootScope()

• MockShinySession$onUnhandledError()

• MockShinySession$unhandledError()

• MockShinySession$freezeValue()

• MockShinySession$onSessionEnded()

• MockShinySession$registerDownload()

• MockShinySession$getCurrentOutputInfo()

• MockShinySession$clone()

Method new()

Create a new MockShinySession.

Usage

MockShinySession$new()

Method onFlush()

Define a callback to be invoked before a reactive flush

Usage

MockShinySession$onFlush(fun, once = TRUE)

Arguments

Method onFlushed()

Define a callback to be invoked after a reactive flush

Usage

MockShinySession$onFlushed(fun, once = TRUE)

Arguments

Method onEnded()

Define a callback to be invoked when the session ends

Usage

MockShinySession$onEnded(sessionEndedCallback)

Arguments

Method isEnded()

Returns FALSE if the session has not yet been closed

Usage

MockShinySession$isEnded()

Method isClosed()

Returns FALSE if the session has not yet been closed

Usage

MockShinySession$isClosed()

Method close()

Closes the session

Usage

MockShinySession$close()

Method cycleStartAction()

Unsophisticated mock implementation that merely invokes

Usage

MockShinySession$cycleStartAction(callback)

Arguments

Method fileUrl()

Base64-encode the given file. Needed for image rendering.

Usage

MockShinySession$fileUrl(name, file, contentType = "application/octet-stream")

Arguments

Method setInputs()

Sets reactive values associated with the session$inputs object and flushes the reactives.

Usage

MockShinySession$setInputs(...)

Arguments

Examples

\dontrun{
session$setInputs(x=1, y=2)
}

Method .scheduleTask()

An internal method which shouldn't be used by others. Schedules callback for execution after some number of millis milliseconds.

Usage

MockShinySession$.scheduleTask(millis, callback)

Arguments

Method elapse()

Simulate the passing of time by the given number of milliseconds.

Usage

MockShinySession$elapse(millis)

Arguments

Method .now()

An internal method which shouldn't be used by others.

Usage

MockShinySession$.now()

Returns

Elapsed time in milliseconds.

Method defineOutput()

An internal method which shouldn't be used by others. Defines an output in a way that sets private$currentOutputName appropriately.

Usage

MockShinySession$defineOutput(name, func, label)

Arguments

Method getOutput()

An internal method which shouldn't be used by others. Forces evaluation of any reactive dependencies of the output function.

Usage

MockShinySession$getOutput(name)

Arguments

Returns

The return value of the function responsible for rendering the output.

Method ns()

Returns the given id prefixed by this namespace's id.

Usage

MockShinySession$ns(id)

Arguments

Returns

The id with a namespace prefix.

Method flushReact()

Trigger a reactive flush right now.

Usage

MockShinySession$flushReact()

Method makeScope()

Create and return a namespace-specific session proxy.

Usage

MockShinySession$makeScope(namespace)

Arguments

Returns

A new session proxy.

Method setEnv()

Set the environment associated with a testServer() call, but only if it has not previously been set. This ensures that only the environment of the outermost module under test is the one retained. In other words, the first assignment wins.

Usage

MockShinySession$setEnv(env)

Arguments

Returns

The provided env.

Method setReturned()

Set the value returned by the module call and proactively flush. Note that this method may be called multiple times if modules are nested. The last assignment, corresponding to an invocation of setReturned() in the outermost module, wins.

Usage

MockShinySession$setReturned(value)

Arguments

Returns

The provided value.

Method getReturned()

Get the value returned by the module call.

Usage

MockShinySession$getReturned()

Returns

The value returned by the module call

Method genId()

Generate a distinct character identifier for use as a proxy namespace.

Usage

MockShinySession$genId()

Returns

A character identifier unique to the current session.

Method rootScope()

Provides a way to access the root MockShinySession from any descendant proxy.

Usage

MockShinySession$rootScope()

Returns

The root MockShinySession.

Method onUnhandledError()

Add an unhandled error callback.

Usage

MockShinySession$onUnhandledError(callback)

Arguments

Returns

A deregistration function.

Method unhandledError()

Called by observers when a reactive expression errors.

Usage

MockShinySession$unhandledError(e, close = TRUE)

Arguments

Method freezeValue()

Freeze a value until the flush cycle completes.

Usage

MockShinySession$freezeValue(x, name)

Arguments

Method onSessionEnded()

Registers the given callback to be invoked when the session is closed (i.e. the connection to the client has been severed). The return value is a function which unregisters the callback. If multiple callbacks are registered, the order in which they are invoked is not guaranteed.

Usage

MockShinySession$onSessionEnded(sessionEndedCallback)

Arguments

Method registerDownload()

Associated a downloadable file with the session.

Usage

MockShinySession$registerDownload(name, filename, contentType, content)

Arguments

Method getCurrentOutputInfo()

Get information about the output that is currently being executed.

Usage

MockShinySession$getCurrentOutputInfo()

Returns

A list with with the name of the output. If no output is currently being executed, this will return NULL. output, or NULL if no output is currently executing.

Method clone()

The objects of this class are cloneable with this method.

Usage

MockShinySession$clone(deep = FALSE)

Arguments

Examples

## ------------------------------------------------
## Method `MockShinySession$setInputs`
## ------------------------------------------------

## Not run: 
session$setInputs(x=1, y=2)

## End(Not run)

Create a modal dialog UI

Description

modalDialog() creates the UI for a modal dialog, using Bootstrap's modal class. Modals are typically used for showing important messages, or for presenting UI that requires input from the user, such as a user name and password input.

modalButton() creates a button that will dismiss the dialog when clicked, typically used when customising the footer.

Usage

modalDialog(
  ...,
  title = NULL,
  footer = modalButton("Dismiss"),
  size = c("m", "s", "l", "xl"),
  easyClose = FALSE,
  fade = TRUE
)

modalButton(label, icon = NULL)

Arguments

Examples

if (interactive()) {
# Display an important message that can be dismissed only by clicking the
# dismiss button.
shinyApp(
  ui = basicPage(
    actionButton("show", "Show modal dialog")
  ),
  server = function(input, output) {
    observeEvent(input$show, {
      showModal(modalDialog(
        title = "Important message",
        "This is an important message!"
      ))
    })
  }
)


# Display a message that can be dismissed by clicking outside the modal dialog,
# or by pressing Esc.
shinyApp(
  ui = basicPage(
    actionButton("show", "Show modal dialog")
  ),
  server = function(input, output) {
    observeEvent(input$show, {
      showModal(modalDialog(
        title = "Somewhat important message",
        "This is a somewhat important message.",
        easyClose = TRUE,
        footer = NULL
      ))
    })
  }
)


# Display a modal that requires valid input before continuing.
shinyApp(
  ui = basicPage(
    actionButton("show", "Show modal dialog"),
    verbatimTextOutput("dataInfo")
  ),

  server = function(input, output) {
    # reactiveValues object for storing current data set.
    vals <- reactiveValues(data = NULL)

    # Return the UI for a modal dialog with data selection input. If 'failed' is
    # TRUE, then display a message that the previous value was invalid.
    dataModal <- function(failed = FALSE) {
      modalDialog(
        textInput("dataset", "Choose data set",
          placeholder = 'Try "mtcars" or "abc"'
        ),
        span('(Try the name of a valid data object like "mtcars", ',
             'then a name of a non-existent object like "abc")'),
        if (failed)
          div(tags$b("Invalid name of data object", style = "color: red;")),

        footer = tagList(
          modalButton("Cancel"),
          actionButton("ok", "OK")
        )
      )
    }

    # Show modal when button is clicked.
    observeEvent(input$show, {
      showModal(dataModal())
    })

    # When OK button is pressed, attempt to load the data set. If successful,
    # remove the modal. If not show another modal, but this time with a failure
    # message.
    observeEvent(input$ok, {
      # Check that data object exists and is data frame.
      if (!is.null(input$dataset) && nzchar(input$dataset) &&
          exists(input$dataset) && is.data.frame(get(input$dataset))) {
        vals$data <- get(input$dataset)
        removeModal()
      } else {
        showModal(dataModal(failed = TRUE))
      }
    })

    # Display information about selected data
    output$dataInfo <- renderPrint({
      if (is.null(vals$data))
        "No data selected"
      else
        summary(vals$data)
    })
  }
)
}

Shiny modules

Description

Shiny's module feature lets you break complicated UI and server logic into smaller, self-contained pieces. Compared to large monolithic Shiny apps, modules are easier to reuse and easier to reason about. See the article at https://shiny.rstudio.com/articles/modules.html to learn more.

Usage

moduleServer(id, module, session = getDefaultReactiveDomain())

Arguments

Details

Starting in Shiny 1.5.0, we recommend using moduleServer instead of callModule(), because the syntax is a little easier to understand, and modules created with moduleServer can be tested with testServer().

Value

The return value, if any, from executing the module server function

See Also

https://shiny.rstudio.com/articles/modules.html

Examples

# Define the UI for a module
counterUI <- function(id, label = "Counter") {
  ns <- NS(id)
  tagList(
    actionButton(ns("button"), label = label),
    verbatimTextOutput(ns("out"))
  )
}

# Define the server logic for a module
counterServer <- function(id) {
  moduleServer(
    id,
    function(input, output, session) {
      count <- reactiveVal(0)
      observeEvent(input$button, {
        count(count() + 1)
      })
      output$out <- renderText({
        count()
      })
      count
    }
  )
}

# Use the module in an app
ui <- fluidPage(
  counterUI("counter1", "Counter #1"),
  counterUI("counter2", "Counter #2")
)
server <- function(input, output, session) {
  counterServer("counter1")
  counterServer("counter2")
}
if (interactive()) {
  shinyApp(ui, server)
}



# If you want to pass extra parameters to the module's server logic, you can
# add them to your function. In this case `prefix` is text that will be
# printed before the count.
counterServer2 <- function(id, prefix = NULL) {
  moduleServer(
    id,
    function(input, output, session) {
      count <- reactiveVal(0)
      observeEvent(input$button, {
        count(count() + 1)
      })
      output$out <- renderText({
        paste0(prefix, count())
      })
      count
    }
  )
}

ui <- fluidPage(
  counterUI("counter", "Counter"),
)
server <- function(input, output, session) {
  counterServer2("counter", "The current count is: ")
}
if (interactive()) {
  shinyApp(ui, server)
}

Create a page with a top level navigation bar

Description

Create a page that contains a top level navigation bar that can be used to toggle a set of tabPanel() elements.

Usage

navbarPage(
  title,
  ...,
  id = NULL,
  selected = NULL,
  position = c("static-top", "fixed-top", "fixed-bottom"),
  header = NULL,
  footer = NULL,
  inverse = FALSE,
  collapsible = FALSE,
  fluid = TRUE,
  theme = NULL,
  windowTitle = NA,
  lang = NULL
)

navbarMenu(title, ..., menuName = title, icon = NULL)

Arguments

Details

The navbarMenu function can be used to create an embedded menu within the navbar that in turns includes additional tabPanels (see example below).

Value

A UI definition that can be passed to the shinyUI function.

See Also

tabPanel(), tabsetPanel(), updateNavbarPage(), insertTab(), showTab()

Other layout functions: fillPage(), fixedPage(), flowLayout(), fluidPage(), sidebarLayout(), splitLayout(), verticalLayout()

Examples

navbarPage("App Title",
  tabPanel("Plot"),
  tabPanel("Summary"),
  tabPanel("Table")
)

navbarPage("App Title",
  tabPanel("Plot"),
  navbarMenu("More",
    tabPanel("Summary"),
    "----",
    "Section header",
    tabPanel("Table")
  )
)

Create a navigation list panel

Description

Create a navigation list panel that provides a list of links on the left which navigate to a set of tabPanels displayed to the right.

Usage

navlistPanel(
  ...,
  id = NULL,
  selected = NULL,
  header = NULL,
  footer = NULL,
  well = TRUE,
  fluid = TRUE,
  widths = c(4, 8)
)

Arguments

Details

You can include headers within the navlistPanel by including plain text elements in the list. Versions of Shiny before 0.11 supported separators with "——", but as of 0.11, separators were no longer supported. This is because version 0.11 switched to Bootstrap 3, which doesn't support separators.

See Also

tabPanel(), updateNavlistPanel(), insertTab(), showTab()

Examples

fluidPage(

  titlePanel("Application Title"),

  navlistPanel(
    "Header",
    tabPanel("First"),
    tabPanel("Second"),
    tabPanel("Third")
  )
)

Namespaced IDs for inputs/outputs

Description

The NS function creates namespaced IDs out of bare IDs, by joining them using ns.sep as the delimiter. It is intended for use in Shiny modules. See https://shiny.rstudio.com/articles/modules.html.

Usage

NS(namespace, id = NULL)

ns.sep

Arguments

Format

An object of class character of length 1.

Details

Shiny applications use IDs to identify inputs and outputs. These IDs must be unique within an application, as accidentally using the same input/output ID more than once will result in unexpected behavior. The traditional solution for preventing name collisions is namespaces; a namespace is to an ID as a directory is to a file. Use the NS function to turn a bare ID into a namespaced one, by combining them with ns.sep in between.

Value

If id is missing, returns a function that expects an id string as its only argument and returns that id with the namespace prepended.

See Also

https://shiny.rstudio.com/articles/modules.html

Create a numeric input control

Description

Create an input control for entry of numeric values

Usage

numericInput(
  inputId,
  label,
  value,
  min = NA,
  max = NA,
  step = NA,
  width = NULL
)

Arguments

Value

A numeric input control that can be added to a UI definition.

Server value

A numeric vector of length 1.

See Also

updateNumericInput()

Other input elements: actionButton(), checkboxGroupInput(), checkboxInput(), dateInput(), dateRangeInput(), fileInput(), passwordInput(), radioButtons(), selectInput(), sliderInput(), submitButton(), textAreaInput(), textInput(), varSelectInput()

Examples

## Only run examples in interactive R sessions
if (interactive()) {

ui <- fluidPage(
  numericInput("obs", "Observations:", 10, min = 1, max = 100),
  verbatimTextOutput("value")
)
server <- function(input, output) {
  output$value <- renderText({ input$obs })
}
shinyApp(ui, server)
}

Create a reactive observer

Description

Creates an observer from the given expression.

Usage

observe(
  x,
  env = parent.frame(),
  quoted = FALSE,
  ...,
  label = NULL,
  suspended = FALSE,
  priority = 0,
  domain = getDefaultReactiveDomain(),
  autoDestroy = TRUE,
  ..stacktraceon = TRUE
)

Arguments

Details

An observer is like a reactive expression in that it can read reactive values and call reactive expressions, and will automatically re-execute when those dependencies change. But unlike reactive expressions, it doesn't yield a result and can't be used as an input to other reactive expressions. Thus, observers are only useful for their side effects (for example, performing I/O).

Another contrast between reactive expressions and observers is their execution strategy. Reactive expressions use lazy evaluation; that is, when their dependencies change, they don't re-execute right away but rather wait until they are called by someone else. Indeed, if they are not called then they will never re-execute. In contrast, observers use eager evaluation; as soon as their dependencies change, they schedule themselves to re-execute.

Starting with Shiny 0.10.0, observers are automatically destroyed by default when the domain that owns them ends (e.g. when a Shiny session ends).

Value

An observer reference class object. This object has the following methods:

suspend()

Causes this observer to stop scheduling flushes (re-executions) in response to invalidations. If the observer was invalidated prior to this call but it has not re-executed yet then that re-execution will still occur, because the flush is already scheduled.

resume()

Causes this observer to start re-executing in response to invalidations. If the observer was invalidated while suspended, then it will schedule itself for re-execution.

destroy()

Stops the observer from executing ever again, even if it is currently scheduled for re-execution.

setPriority(priority = 0)

Change this observer's priority. Note that if the observer is currently invalidated, then the change in priority will not take effect until the next invalidation–unless the observer is also currently suspended, in which case the priority change will be effective upon resume.

setAutoDestroy(autoDestroy)

Sets whether this observer should be automatically destroyed when its domain (if any) ends. If autoDestroy is TRUE and the domain already ended, then destroy() is called immediately."

onInvalidate(callback)

Register a callback function to run when this observer is invalidated. No arguments will be provided to the callback function when it is invoked.

Examples

values <- reactiveValues(A=1)

obsB <- observe({
  print(values$A + 1)
})

# To store expressions for later conversion to observe, use rlang::quo()
myquo <- rlang::quo({ print(values$A + 3) })
obsC <- rlang::inject(observe(!!myquo))

# (Legacy) Can use quoted expressions
obsD <- observe(quote({ print(values$A + 2) }), quoted = TRUE)

# In a normal Shiny app, the web client will trigger flush events. If you
# are at the console, you can force a flush with flushReact()
shiny:::flushReact()

Event handler

Description

Respond to "event-like" reactive inputs, values, and expressions. As of Shiny 1.6.0, we recommend using bindEvent() instead of eventReactive() and observeEvent(). This is because bindEvent() can be composed with bindCache(), and because it can also be used with render functions (like renderText() and renderPlot()).

Usage

observeEvent(
  eventExpr,
  handlerExpr,
  event.env = parent.frame(),
  event.quoted = FALSE,
  handler.env = parent.frame(),
  handler.quoted = FALSE,
  ...,
  label = NULL,
  suspended = FALSE,
  priority = 0,
  domain = getDefaultReactiveDomain(),
  autoDestroy = TRUE,
  ignoreNULL = TRUE,
  ignoreInit = FALSE,
  once = FALSE
)

eventReactive(
  eventExpr,
  valueExpr,
  event.env = parent.frame(),
  event.quoted = FALSE,
  value.env = parent.frame(),
  value.quoted = FALSE,
  ...,
  label = NULL,
  domain = getDefaultReactiveDomain(),
  ignoreNULL = TRUE,
  ignoreInit = FALSE
)

Arguments

Details

Shiny's reactive programming framework is primarily designed for calculated values (reactive expressions) and side-effect-causing actions (observers) that respond to any of their inputs changing. That's often what is desired in Shiny apps, but not always: sometimes you want to wait for a specific action to be taken from the user, like clicking an actionButton(), before calculating an expression or taking an action. A reactive value or expression that is used to trigger other calculations in this way is called an event.

These situations demand a more imperative, "event handling" style of programming that is possible–but not particularly intuitive–using the reactive programming primitives observe() and isolate(). observeEvent and eventReactive provide straightforward APIs for event handling that wrap observe and isolate.

Use observeEvent whenever you want to perform an action in response to an event. (Note that "recalculate a value" does not generally count as performing an action–see eventReactive for that.) The first argument is the event you want to respond to, and the second argument is a function that should be called whenever the event occurs. Note that observeEvent() is equivalent to using observe() %>% bindEvent() and as of Shiny 1.6.0, we recommend the latter.

Use eventReactive to create a calculated value that only updates in response to an event. This is just like a normal reactive expression except it ignores all the usual invalidations that come from its reactive dependencies; it only invalidates in response to the given event. Note that eventReactive() is equivalent to using reactive() %>% bindEvent() and as of Shiny 1.6.0, we recommend the latter.

Value

observeEvent returns an observer reference class object (see observe()). eventReactive returns a reactive expression object (see reactive()).

ignoreNULL and ignoreInit

Both observeEvent and eventReactive take an ignoreNULL parameter that affects behavior when the eventExpr evaluates to NULL (or in the special case of an actionButton(), 0). In these cases, if ignoreNULL is TRUE, then an observeEvent will not execute and an eventReactive will raise a silent validation error. This is useful behavior if you don't want to do the action or calculation when your app first starts, but wait for the user to initiate the action first (like a "Submit" button); whereas ignoreNULL=FALSE is desirable if you want to initially perform the action/calculation and just let the user re-initiate it (like a "Recalculate" button).

Likewise, both observeEvent and eventReactive also take in an ignoreInit argument. By default, both of these will run right when they are created (except if, at that moment, eventExpr evaluates to NULL and ignoreNULL is TRUE). But when responding to a click of an action button, it may often be useful to set ignoreInit to TRUE. For example, if you're setting up an observeEvent for a dynamically created button, then ignoreInit = TRUE will guarantee that the action (in handlerExpr) will only be triggered when the button is actually clicked, instead of also being triggered when it is created/initialized. Similarly, if you're setting up an eventReactive that responds to a dynamically created button used to refresh some data (then returned by that eventReactive), then you should use ⁠eventReactive([...], ignoreInit = TRUE)⁠ if you want to let the user decide if/when they want to refresh the data (since, depending on the app, this may be a computationally expensive operation).

Even though ignoreNULL and ignoreInit can be used for similar purposes they are independent from one another. Here's the result of combining these:

ignoreNULL = TRUE and ignoreInit = FALSE

This is the default. This combination means that handlerExpr/ valueExpr will run every time that eventExpr is not NULL. If, at the time of the creation of the observeEvent/eventReactive, eventExpr happens to not be NULL, then the code runs.

ignoreNULL = FALSE and ignoreInit = FALSE

This combination means that handlerExpr/valueExpr will run every time no matter what.

ignoreNULL = FALSE and ignoreInit = TRUE

This combination means that handlerExpr/valueExpr will not run when the observeEvent/eventReactive is created (because ignoreInit = TRUE), but it will run every other time.

ignoreNULL = TRUE and ignoreInit = TRUE

This combination means that handlerExpr/valueExpr will not run when the observeEvent/eventReactive is created (because ignoreInit = TRUE). After that, handlerExpr/valueExpr will run every time that eventExpr is not NULL.

See Also

actionButton()

Examples

## Only run examples in interactive R sessions
if (interactive()) {

  ## App 1: Sample usage
  shinyApp(
    ui = fluidPage(
      column(4,
        numericInput("x", "Value", 5),
        br(),
        actionButton("button", "Show")
      ),
      column(8, tableOutput("table"))
    ),
    server = function(input, output) {
      # Take an action every time button is pressed;
      # here, we just print a message to the console
      observeEvent(input$button, {
        cat("Showing", input$x, "rows\n")
      })
      # The observeEvent() above is equivalent to:
      # observe({
      #    cat("Showing", input$x, "rows\n")
      #   }) %>%
      #   bindEvent(input$button)

      # Take a reactive dependency on input$button, but
      # not on any of the stuff inside the function
      df <- eventReactive(input$button, {
        head(cars, input$x)
      })
      output$table <- renderTable({
        df()
      })
    }
  )

  ## App 2: Using `once`
  shinyApp(
    ui = basicPage( actionButton("go", "Go")),
    server = function(input, output, session) {
      observeEvent(input$go, {
        print(paste("This will only be printed once; all",
              "subsequent button clicks won't do anything"))
      }, once = TRUE)
      # The observeEvent() above is equivalent to:
      # observe({
      #   print(paste("This will only be printed once; all",
      #         "subsequent button clicks won't do anything"))
      #   }) %>%
      #   bindEvent(input$go, once = TRUE)
    }
  )

  ## App 3: Using `ignoreInit` and `once`
  shinyApp(
    ui = basicPage(actionButton("go", "Go")),
    server = function(input, output, session) {
      observeEvent(input$go, {
        insertUI("#go", "afterEnd",
                 actionButton("dynamic", "click to remove"))

        # set up an observer that depends on the dynamic
        # input, so that it doesn't run when the input is
        # created, and only runs once after that (since
        # the side effect is remove the input from the DOM)
        observeEvent(input$dynamic, {
          removeUI("#dynamic")
        }, ignoreInit = TRUE, once = TRUE)
      })
    }
  )
}

Add callbacks for Shiny session bookmarking events

Description

These functions are for registering callbacks on Shiny session events. They should be called within an application's server function.

• onBookmark registers a function that will be called just before Shiny bookmarks state.

• onBookmarked registers a function that will be called just after Shiny bookmarks state.

• onRestore registers a function that will be called when a session is restored, after the server function executes, but before all other reactives, observers and render functions are run.

• onRestored registers a function that will be called after a session is restored. This is similar to onRestore, but it will be called after all reactives, observers, and render functions run, and after results are sent to the client browser. onRestored callbacks can be useful for sending update messages to the client browser.

Usage

onBookmark(fun, session = getDefaultReactiveDomain())

onBookmarked(fun, session = getDefaultReactiveDomain())

onRestore(fun, session = getDefaultReactiveDomain())

onRestored(fun, session = getDefaultReactiveDomain())

Arguments

Details

All of these functions return a function which can be called with no arguments to cancel the registration.

The callback function that is passed to these functions should take one argument, typically named "state" (for onBookmark, onRestore, and onRestored) or "url" (for onBookmarked).

For onBookmark, the state object has three relevant fields. The values field is an environment which can be used to save arbitrary values (see examples). If the state is being saved to disk (as opposed to being encoded in a URL), the dir field contains the name of a directory which can be used to store extra files. Finally, the state object has an input field, which is simply the application's input object. It can be read, but not modified.

For onRestore and onRestored, the state object is a list. This list contains input, which is a named list of input values to restore, values, which is an environment containing arbitrary values that were saved in onBookmark, and dir, the name of the directory that the state is being restored from, and which could have been used to save extra files.

For onBookmarked, the callback function receives a string with the bookmark URL. This callback function should be used to display UI in the client browser with the bookmark URL. If no callback function is registered, then Shiny will by default display a modal dialog with the bookmark URL.

Modules

These callbacks may also be used in Shiny modules. When used this way, the inputs and values will automatically be namespaced for the module, and the callback functions registered for the module will only be able to see the module's inputs and values.

See Also

enableBookmarking for general information on bookmarking.

Examples

## Only run these examples in interactive sessions
if (interactive()) {

# Basic use of onBookmark and onRestore: This app saves the time in its
# arbitrary values, and restores that time when the app is restored.
ui <- function(req) {
  fluidPage(
    textInput("txt", "Input text"),
    bookmarkButton()
  )
}
server <- function(input, output) {
  onBookmark(function(state) {
    savedTime <- as.character(Sys.time())
    cat("Last saved at", savedTime, "\n")
    # state is a mutable reference object, and we can add arbitrary values to
    # it.
    state$values$time <- savedTime
  })

  onRestore(function(state) {
    cat("Restoring from state bookmarked at", state$values$time, "\n")
  })
}
enableBookmarking("url")
shinyApp(ui, server)



ui <- function(req) {
  fluidPage(
    textInput("txt", "Input text"),
    bookmarkButton()
  )
}
server <- function(input, output, session) {
  lastUpdateTime <- NULL

  observeEvent(input$txt, {
    updateTextInput(session, "txt",
      label = paste0("Input text (Changed ", as.character(Sys.time()), ")")
    )
  })

  onBookmark(function(state) {
    # Save content to a file
    messageFile <- file.path(state$dir, "message.txt")
    cat(as.character(Sys.time()), file = messageFile)
  })

  onRestored(function(state) {
    # Read the file
    messageFile <- file.path(state$dir, "message.txt")
    timeText <- readChar(messageFile, 1000)

    # updateTextInput must be called in onRestored, as opposed to onRestore,
    # because onRestored happens after the client browser is ready.
    updateTextInput(session, "txt",
      label = paste0("Input text (Changed ", timeText, ")")
    )
  })
}
# "server" bookmarking is needed for writing to disk.
enableBookmarking("server")
shinyApp(ui, server)


# This app has a module, and both the module and the main app code have
# onBookmark and onRestore functions which write and read state$values$hash. The
# module's version of state$values$hash does not conflict with the app's version
# of state$values$hash.
#
# A basic module that captializes text.
capitalizerUI <- function(id) {
  ns <- NS(id)
  wellPanel(
    h4("Text captializer module"),
    textInput(ns("text"), "Enter text:"),
    verbatimTextOutput(ns("out"))
  )
}
capitalizerServer <- function(input, output, session) {
  output$out <- renderText({
    toupper(input$text)
  })
  onBookmark(function(state) {
    state$values$hash <- rlang::hash(input$text)
  })
  onRestore(function(state) {
    if (identical(rlang::hash(input$text), state$values$hash)) {
      message("Module's input text matches hash ", state$values$hash)
    } else {
      message("Module's input text does not match hash ", state$values$hash)
    }
  })
}
# Main app code
ui <- function(request) {
  fluidPage(
    sidebarLayout(
      sidebarPanel(
        capitalizerUI("tc"),
        textInput("text", "Enter text (not in module):"),
        bookmarkButton()
      ),
      mainPanel()
    )
  )
}
server <- function(input, output, session) {
  callModule(capitalizerServer, "tc")
  onBookmark(function(state) {
    state$values$hash <- rlang::hash(input$text)
  })
  onRestore(function(state) {
    if (identical(rlang::hash(input$text), state$values$hash)) {
      message("App's input text matches hash ", state$values$hash)
    } else {
      message("App's input text does not match hash ", state$values$hash)
    }
  })
}
enableBookmarking(store = "url")
shinyApp(ui, server)
}

Add callbacks for Shiny session events

Description

These functions are for registering callbacks on Shiny session events. onFlush registers a function that will be called before Shiny flushes the reactive system. onFlushed registers a function that will be called after Shiny flushes the reactive system. onUnhandledError registers a function to be called when an unhandled error occurs before the session is closed. onSessionEnded registers a function to be called after the client has disconnected.

These functions should be called within the application's server function.

All of these functions return a function which can be called with no arguments to cancel the registration.

Usage

onFlush(fun, once = TRUE, session = getDefaultReactiveDomain())

onFlushed(fun, once = TRUE, session = getDefaultReactiveDomain())

onSessionEnded(fun, session = getDefaultReactiveDomain())

onUnhandledError(fun, session = getDefaultReactiveDomain())

Arguments

Unhandled Errors

Unhandled errors are errors that aren't otherwise handled by Shiny or by the application logic. In other words, they are errors that will either cause the application to crash or will result in "Error" output in the UI.

You can use onUnhandledError() to register a function that will be called when an unhandled error occurs. This function will be called with the error object as its first argument. If the error is fatal and will result in the session closing, the error condition will have the shiny.error.fatal class.

Note that the onUnhandledError() callbacks cannot be used to prevent the app from closing or to modify the error condition. Instead, they are intended to give you an opportunity to log the error or perform other cleanup operations.

See Also

onStop() for registering callbacks that will be invoked when the application exits, or when a session ends.

Examples

library(shiny)

ui <- fixedPage(
  markdown(c(
    "Set the number to 8 or higher to cause an error",
    "in the `renderText()` output."
  )),
  sliderInput("number", "Number", 0, 10, 4),
  textOutput("text"),
  hr(),
  markdown(c(
    "Click the button below to crash the app with an unhandled error",
    "in an `observe()` block."
  )),
  actionButton("crash", "Crash the app!")
)

log_event <- function(level, ...) {
  ts <- strftime(Sys.time(), " [%F %T] ")
  message(level, ts, ...)
}

server <- function(input, output, session) {
  log_event("INFO", "Session started")

  onUnhandledError(function(err) {
    # log the unhandled error
    level <- if (inherits(err, "shiny.error.fatal")) "FATAL" else "ERROR"
    log_event(level, conditionMessage(err))
  })

  onStop(function() {
    log_event("INFO", "Session ended")
  })

  observeEvent(input$crash, stop("Oops, an unhandled error happened!"))

  output$text <- renderText({
    if (input$number > 7) {
      stop("that's too high!")
    }
    sprintf("You picked number %d.", input$number)
  })
}

shinyApp(ui, server)

Run code after an application or session ends

Description

This function registers callback functions that are invoked when the application exits (when runApp() exits), or after each user session ends (when a client disconnects).

Usage

onStop(fun, session = getDefaultReactiveDomain())

Arguments

Value

A function which, if invoked, will cancel the callback.

See Also

onSessionEnded() for the same functionality, but at the session level only.

Examples

## Only run this example in interactive R sessions
if (interactive()) {
  # Open this application in multiple browsers, then close the browsers.
  shinyApp(
    ui = basicPage("onStop demo"),

    server = function(input, output, session) {
      onStop(function() cat("Session stopped\n"))
    },

    onStart = function() {
      cat("Doing application setup\n")

      onStop(function() {
        cat("Doing application cleanup\n")
      })
    }
  )
}
# In the example above, onStop() is called inside of onStart(). This is
# the pattern that should be used when creating a shinyApp() object from
# a function, or at the console. If instead you are writing an app.R which
# will be invoked with runApp(), you can do it that way, or put the onStop()
# before the shinyApp() call, as shown below.

## Not run: 
# ==== app.R ====
cat("Doing application setup\n")
onStop(function() {
  cat("Doing application cleanup\n")
})

shinyApp(
  ui = basicPage("onStop demo"),

  server = function(input, output, session) {
    onStop(function() cat("Session stopped\n"))
  }
)
# ==== end app.R ====


# Similarly, if you have a global.R, you can call onStop() from there.
# ==== global.R ====
cat("Doing application setup\n")
onStop(function() {
  cat("Doing application cleanup\n")
})
# ==== end global.R ====

## End(Not run)

Set options for an output object.

Description

These are the available options for an output object:

• suspendWhenHidden. When TRUE (the default), the output object will be suspended (not execute) when it is hidden on the web page. When FALSE, the output object will not suspend when hidden, and if it was already hidden and suspended, then it will resume immediately.

• priority. The priority level of the output object. Queued outputs with higher priority values will execute before those with lower values.

Usage

outputOptions(x, name, ...)

Arguments

Examples

## Not run: 
# Get the list of options for all observers within output
outputOptions(output)

# Disable suspend for output$myplot
outputOptions(output, "myplot", suspendWhenHidden = FALSE)

# Change priority for output$myplot
outputOptions(output, "myplot", priority = 10)

# Get the list of options for output$myplot
outputOptions(output, "myplot")

## End(Not run)

Create a page with a sidebar

Description

DEPRECATED: use fluidPage() and sidebarLayout() instead.

Usage

pageWithSidebar(headerPanel, sidebarPanel, mainPanel)

Arguments

Value

A UI definition that can be passed to the shinyUI function

Parse a GET query string from a URL

Description

Returns a named list of key-value pairs.

Usage

parseQueryString(str, nested = FALSE)

Arguments

Examples

parseQueryString("?foo=1&bar=b%20a%20r")

## Not run: 
# Example of usage within a Shiny app
function(input, output, session) {

  output$queryText <- renderText({
    query <- parseQueryString(session$clientData$url_search)

    # Ways of accessing the values
    if (as.numeric(query$foo) == 1) {
      # Do something
    }
    if (query[["bar"]] == "targetstring") {
      # Do something else
    }

    # Return a string with key-value pairs
    paste(names(query), query, sep = "=", collapse=", ")
  })
}

## End(Not run)

Create a password input control

Description

Create an password control for entry of passwords.

Usage

passwordInput(inputId, label, value = "", width = NULL, placeholder = NULL)

Arguments

Value

A text input control that can be added to a UI definition.

Server value

A character string of the password input. The default value is "" unless value is provided.

See Also

updateTextInput()

Other input elements: actionButton(), checkboxGroupInput(), checkboxInput(), dateInput(), dateRangeInput(), fileInput(), numericInput(), radioButtons(), selectInput(), sliderInput(), submitButton(), textAreaInput(), textInput(), varSelectInput()

Examples

## Only run examples in interactive R sessions
if (interactive()) {

ui <- fluidPage(
  passwordInput("password", "Password:"),
  actionButton("go", "Go"),
  verbatimTextOutput("value")
)
server <- function(input, output) {
  output$value <- renderText({
    req(input$go)
    isolate(input$password)
  })
}
shinyApp(ui, server)
}

Create an plot or image output element

Description

Render a renderPlot() or renderImage() within an application page.

Usage

imageOutput(
  outputId,
  width = "100%",
  height = "400px",
  click = NULL,
  dblclick = NULL,
  hover = NULL,
  brush = NULL,
  inline = FALSE,
  fill = FALSE
)

plotOutput(
  outputId,
  width = "100%",
  height = "400px",
  click = NULL,
  dblclick = NULL,
  hover = NULL,
  brush = NULL,
  inline = FALSE,
  fill = !inline
)

Arguments

Value

A plot or image output element that can be included in a panel.

Interactive plots

Plots and images in Shiny support mouse-based interaction, via clicking, double-clicking, hovering, and brushing. When these interaction events occur, the mouse coordinates will be sent to the server as ⁠input$⁠ variables, as specified by click, dblclick, hover, or brush.

For plotOutput, the coordinates will be sent scaled to the data space, if possible. (At the moment, plots generated by base graphics and ggplot2 support this scaling, although plots generated by lattice and others do not.) If scaling is not possible, the raw pixel coordinates will be sent. For imageOutput, the coordinates will be sent in raw pixel coordinates.

With ggplot2 graphics, the code in renderPlot should return a ggplot object; if instead the code prints the ggplot2 object with something like print(p), then the coordinates for interactive graphics will not be properly scaled to the data space.

Note

The arguments clickId and hoverId only work for R base graphics (see the graphics package). They do not work for grid-based graphics, such as ggplot2, lattice, and so on.

See Also

For the corresponding server-side functions, see renderPlot() and renderImage().

Examples

# Only run these examples in interactive R sessions
if (interactive()) {

# A basic shiny app with a plotOutput
shinyApp(
  ui = fluidPage(
    sidebarLayout(
      sidebarPanel(
        actionButton("newplot", "New plot")
      ),
      mainPanel(
        plotOutput("plot")
      )
    )
  ),
  server = function(input, output) {
    output$plot <- renderPlot({
      input$newplot
      # Add a little noise to the cars data
      cars2 <- cars + rnorm(nrow(cars))
      plot(cars2)
    })
  }
)


# A demonstration of clicking, hovering, and brushing
shinyApp(
  ui = basicPage(
    fluidRow(
      column(width = 4,
        plotOutput("plot", height=300,
          click = "plot_click",  # Equiv, to click=clickOpts(id="plot_click")
          hover = hoverOpts(id = "plot_hover", delayType = "throttle"),
          brush = brushOpts(id = "plot_brush")
        ),
        h4("Clicked points"),
        tableOutput("plot_clickedpoints"),
        h4("Brushed points"),
        tableOutput("plot_brushedpoints")
      ),
      column(width = 4,
        verbatimTextOutput("plot_clickinfo"),
        verbatimTextOutput("plot_hoverinfo")
      ),
      column(width = 4,
        wellPanel(actionButton("newplot", "New plot")),
        verbatimTextOutput("plot_brushinfo")
      )
    )
  ),
  server = function(input, output, session) {
    data <- reactive({
      input$newplot
      # Add a little noise to the cars data so the points move
      cars + rnorm(nrow(cars))
    })
    output$plot <- renderPlot({
      d <- data()
      plot(d$speed, d$dist)
    })
    output$plot_clickinfo <- renderPrint({
      cat("Click:\n")
      str(input$plot_click)
    })
    output$plot_hoverinfo <- renderPrint({
      cat("Hover (throttled):\n")
      str(input$plot_hover)
    })
    output$plot_brushinfo <- renderPrint({
      cat("Brush (debounced):\n")
      str(input$plot_brush)
    })
    output$plot_clickedpoints <- renderTable({
      # For base graphics, we need to specify columns, though for ggplot2,
      # it's usually not necessary.
      res <- nearPoints(data(), input$plot_click, "speed", "dist")
      if (nrow(res) == 0)
        return()
      res
    })
    output$plot_brushedpoints <- renderTable({
      res <- brushedPoints(data(), input$plot_brush, "speed", "dist")
      if (nrow(res) == 0)
        return()
      res
    })
  }
)


# Demo of clicking, hovering, brushing with imageOutput
# Note that coordinates are in pixels
shinyApp(
  ui = basicPage(
    fluidRow(
      column(width = 4,
        imageOutput("image", height=300,
          click = "image_click",
          hover = hoverOpts(
            id = "image_hover",
            delay = 500,
            delayType = "throttle"
          ),
          brush = brushOpts(id = "image_brush")
        )
      ),
      column(width = 4,
        verbatimTextOutput("image_clickinfo"),
        verbatimTextOutput("image_hoverinfo")
      ),
      column(width = 4,
        wellPanel(actionButton("newimage", "New image")),
        verbatimTextOutput("image_brushinfo")
      )
    )
  ),
  server = function(input, output, session) {
    output$image <- renderImage({
      input$newimage

      # Get width and height of image output
      width  <- session$clientData$output_image_width
      height <- session$clientData$output_image_height

      # Write to a temporary PNG file
      outfile <- tempfile(fileext = ".png")

      png(outfile, width=width, height=height)
      plot(rnorm(200), rnorm(200))
      dev.off()

      # Return a list containing information about the image
      list(
        src = outfile,
        contentType = "image/png",
        width = width,
        height = height,
        alt = "This is alternate text"
      )
    })
    output$image_clickinfo <- renderPrint({
      cat("Click:\n")
      str(input$image_click)
    })
    output$image_hoverinfo <- renderPrint({
      cat("Hover (throttled):\n")
      str(input$image_hover)
    })
    output$image_brushinfo <- renderPrint({
      cat("Brush (debounced):\n")
      str(input$image_brush)
    })
  }
)

}

Capture a plot as a PNG file.

Description

The PNG graphics device used is determined in the following order:

• If the ragg package is installed (and the shiny.useragg is not set to FALSE), then use ragg::agg_png().

• If a quartz device is available (i.e., capabilities("aqua") is TRUE), then use png(type = "quartz").

• If the Cairo package is installed (and the shiny.usecairo option is not set to FALSE), then use Cairo::CairoPNG().

• Otherwise, use grDevices::png(). In this case, Linux and Windows may not antialias some point shapes, resulting in poor quality output.

Usage

plotPNG(
  func,
  filename = tempfile(fileext = ".png"),
  width = 400,
  height = 400,
  res = 72,
  ...
)

Arguments

Details

A NULL value provided to width or height is ignored (i.e., the default width or height of the graphics device is used).

Value

A path to the newly generated PNG file.

Reporting progress (object-oriented API)

Description

Reporting progress (object-oriented API)

Reporting progress (object-oriented API)

Details

Reports progress to the user during long-running operations.

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

Instantiating a Progress object causes a progress panel to be created, and it will be displayed the first time the set method is called. Calling close will cause the progress panel to be removed.

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 Progress$new(). If you don't want to set the style each time Progress$new is called, you can instead call shinyOptions(progress.style="old") just once, inside the server function.

Methods

Public methods

• Progress$new()

• Progress$set()

• Progress$inc()

• Progress$getMin()

• Progress$getMax()

• Progress$getValue()

• Progress$close()

• Progress$clone()

Method new()

Creates a new progress panel (but does not display it).

Usage

Progress$new(
  session = getDefaultReactiveDomain(),
  min = 0,
  max = 1,
  style = getShinyOption("progress.style", default = "notification")
)

Arguments

Method set()

Updates the progress panel. When called the first time, the progress panel is displayed.

Usage

Progress$set(value = NULL, message = NULL, detail = NULL)

Arguments

Method inc()

Like set, this updates the progress panel. The difference is that inc increases the progress bar by amount, instead of setting it to a specific value.

Usage

Progress$inc(amount = 0.1, message = NULL, detail = NULL)

Arguments

Method getMin()

Returns the minimum value.

Usage

Progress$getMin()

Method getMax()

Returns the maximum value.

Usage

Progress$getMax()

Method getValue()

Returns the current value.

Usage

Progress$getValue()

Method close()

Removes the progress panel. Future calls to set and close will be ignored.

Usage

Progress$close()

Method clone()

The objects of this class are cloneable with this method.

Usage

Progress$clone(deep = FALSE)

Arguments

See Also

withProgress()

Examples

## Only run examples in interactive R sessions
if (interactive()) {

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

server <- function(input, output, session) {
  output$plot <- renderPlot({
    progress <- Progress$new(session, min=1, max=15)
    on.exit(progress$close())

    progress$set(message = 'Calculation in progress',
                 detail = 'This may take a while...')

    for (i in 1:15) {
      progress$set(value = i)
      Sys.sleep(0.5)
    }
    plot(cars)
  })
}

shinyApp(ui, server)
}

Create radio buttons

Description

Create a set of radio buttons used to select an item from a list.

Usage

radioButtons(
  inputId,
  label,
  choices = NULL,
  selected = NULL,
  inline = FALSE,
  width = NULL,
  choiceNames = NULL,
  choiceValues = NULL
)

Arguments

Details

If you need to represent a "None selected" state, it's possible to default the radio buttons to have no options selected by using selected = character(0). However, this is not recommended, as it gives the user no way to return to that state once they've made a selection. Instead, consider having the first of your choices be c("None selected" = "").

Value

A set of radio buttons that can be added to a UI definition.

Server value

A character string containing the value of the selected button.

See Also

updateRadioButtons()

Other input elements: actionButton(), checkboxGroupInput(), checkboxInput(), dateInput(), dateRangeInput(), fileInput(), numericInput(), passwordInput(), selectInput(), sliderInput(), submitButton(), textAreaInput(), textInput(), varSelectInput()

Examples

## Only run examples in interactive R sessions
if (interactive()) {

ui <- fluidPage(
  radioButtons("dist", "Distribution type:",
               c("Normal" = "norm",
                 "Uniform" = "unif",
                 "Log-normal" = "lnorm",
                 "Exponential" = "exp")),
  plotOutput("distPlot")
)

server <- function(input, output) {
  output$distPlot <- renderPlot({
    dist <- switch(input$dist,
                   norm = rnorm,
                   unif = runif,
                   lnorm = rlnorm,
                   exp = rexp,
                   rnorm)

    hist(dist(500))
  })
}

shinyApp(ui, server)

ui <- fluidPage(
  radioButtons("rb", "Choose one:",
               choiceNames = list(
                 icon("calendar"),
                 HTML("<p style='color:red;'>Red Text</p>"),
                 "Normal text"
               ),
               choiceValues = list(
                 "icon", "html", "text"
               )),
  textOutput("txt")
)

server <- function(input, output) {
  output$txt <- renderText({
    paste("You chose", input$rb)
  })
}

shinyApp(ui, server)
}

Create a reactive expression

Description

Wraps a normal expression to create a reactive expression. Conceptually, a reactive expression is a expression whose result will change over time.

Usage

reactive(
  x,
  env = parent.frame(),
  quoted = FALSE,
  ...,
  label = NULL,
  domain = getDefaultReactiveDomain(),
  ..stacktraceon = TRUE
)

is.reactive(x)

Arguments

Details

Reactive expressions are expressions that can read reactive values and call other reactive expressions. Whenever a reactive value changes, any reactive expressions that depended on it are marked as "invalidated" and will automatically re-execute if necessary. If a reactive expression is marked as invalidated, any other reactive expressions that recently called it are also marked as invalidated. In this way, invalidations ripple through the expressions that depend on each other.

See the Shiny tutorial for more information about reactive expressions.

Value

a function, wrapped in a S3 class "reactive"

Examples

library(rlang)
values <- reactiveValues(A=1)

reactiveB <- reactive({
  values$A + 1
})
# View the values from the R console with isolate()
isolate(reactiveB())
# 2

# To store expressions for later conversion to reactive, use quote()
myquo <- rlang::quo(values$A + 2)
# Unexpected value! Sending a quosure directly will not work as expected.
reactiveC <- reactive(myquo)
# We'd hope for `3`, but instead we get the quosure that was supplied.
isolate(reactiveC())

# Instead, the quosure should be `rlang::inject()`ed
reactiveD <- rlang::inject(reactive(!!myquo))
isolate(reactiveD())
# 3

# (Legacy) Can use quoted expressions
expr <- quote({ values$A + 3 })
reactiveE <- reactive(expr, quoted = TRUE)
isolate(reactiveE())
# 4

Activate reactivity in the console

Description

This is an experimental feature that allows you to enable reactivity at the console, for the purposes of experimentation and learning.

Usage

reactiveConsole(enabled)

Arguments

Examples

reactiveConsole(TRUE)
x <- reactiveVal(10)
y <- observe({
  message("The value of x is ", x())
})
x(20)
x(30)
reactiveConsole(FALSE)

Reactive file reader

Description

Given a file path and read function, returns a reactive data source for the contents of the file.

Usage

reactiveFileReader(intervalMillis, session, filePath, readFunc, ...)

Arguments

Details

reactiveFileReader works by periodically checking the file's last modified time; if it has changed, then the file is re-read and any reactive dependents are invalidated.

The intervalMillis, filePath, and readFunc functions will each be executed in a reactive context; therefore, they may read reactive values and reactive expressions.

Value

A reactive expression that returns the contents of the file, and automatically invalidates when the file changes on disk (as determined by last modified time).

See Also

reactivePoll()

Examples

## Not run: 
# Per-session reactive file reader
function(input, output, session) {
  fileData <- reactiveFileReader(1000, session, 'data.csv', read.csv)

  output$data <- renderTable({
    fileData()
  })
}

# Cross-session reactive file reader. In this example, all sessions share
# the same reader, so read.csv only gets executed once no matter how many
# user sessions are connected.
fileData <- reactiveFileReader(1000, NULL, 'data.csv', read.csv)
function(input, output, session) {
  output$data <- renderTable({
    fileData()
  })
}

## End(Not run)

Reactive polling

Description

Used to create a reactive data source, which works by periodically polling a non-reactive data source.

Usage

reactivePoll(intervalMillis, session, checkFunc, valueFunc)

Arguments

Details

reactivePoll works by pairing a relatively cheap "check" function with a more expensive value retrieval function. The check function will be executed periodically and should always return a consistent value until the data changes. When the check function returns a different value, then the value retrieval function will be used to re-populate the data.

Note that the check function doesn't return TRUE or FALSE to indicate whether the underlying data has changed. Rather, the check function indicates change by returning a different value from the previous time it was called.

For example, reactivePoll is used to implement reactiveFileReader by pairing a check function that simply returns the last modified timestamp of a file, and a value retrieval function that actually reads the contents of the file.

As another example, one might read a relational database table reactively by using a check function that does ⁠SELECT MAX(timestamp) FROM table⁠ and a value retrieval function that does ⁠SELECT * FROM table⁠.

The intervalMillis, checkFunc, and valueFunc functions will be executed in a reactive context; therefore, they may read reactive values and reactive expressions.

Value

A reactive expression that returns the result of valueFunc, and invalidates when checkFunc changes.

See Also

reactiveFileReader()

Examples

function(input, output, session) {

  data <- reactivePoll(1000, session,
    # This function returns the time that log_file was last modified
    checkFunc = function() {
      if (file.exists(log_file))
        file.info(log_file)$mtime[1]
      else
        ""
    },
    # This function returns the content of log_file
    valueFunc = function() {
      read.csv(log_file)
    }
  )

  output$dataTable <- renderTable({
    data()
  })
}

Timer

Description

Creates a reactive timer with the given interval. A reactive timer is like a reactive value, except reactive values are triggered when they are set, while reactive timers are triggered simply by the passage of time.

Usage

reactiveTimer(intervalMs = 1000, session = getDefaultReactiveDomain())

Arguments

Details

Reactive expressions and observers that want to be invalidated by the timer need to call the timer function that reactiveTimer returns, even if the current time value is not actually needed.

See invalidateLater() as a safer and simpler alternative.

Value

A no-parameter function that can be called from a reactive context, in order to cause that context to be invalidated the next time the timer interval elapses. Calling the returned function also happens to yield the current time (as in base::Sys.time()).

See Also

invalidateLater()

Examples

## Only run examples in interactive R sessions
if (interactive()) {

ui <- fluidPage(
  sliderInput("n", "Number of observations", 2, 1000, 500),
  plotOutput("plot")
)

server <- function(input, output) {

  # Anything that calls autoInvalidate will automatically invalidate
  # every 2 seconds.
  autoInvalidate <- reactiveTimer(2000)

  observe({
    # Invalidate and re-execute this reactive expression every time the
    # timer fires.
    autoInvalidate()

    # Do something each time this is invalidated.
    # The isolate() makes this observer _not_ get invalidated and re-executed
    # when input$n changes.
    print(paste("The value of input$n is", isolate(input$n)))
  })

  # Generate a new histogram each time the timer fires, but not when
  # input$n changes.
  output$plot <- renderPlot({
    autoInvalidate()
    hist(rnorm(isolate(input$n)))
  })
}

shinyApp(ui, server)
}

Create a (single) reactive value

Description

The reactiveVal function is used to construct a "reactive value" object. This is an object used for reading and writing a value, like a variable, but with special capabilities for reactive programming. When you read the value out of a reactiveVal object, the calling reactive expression takes a dependency, and when you change the value, it notifies any reactives that previously depended on that value.

Usage

reactiveVal(value = NULL, label = NULL)

Arguments

Details

reactiveVal is very similar to reactiveValues(), except that the former is for a single reactive value (like a variable), whereas the latter lets you conveniently use multiple reactive values by name (like a named list of variables). For a one-off reactive value, it's more natural to use reactiveVal. See the Examples section for an illustration.

Value

A function. Call the function with no arguments to (reactively) read the value; call the function with a single argument to set the value.

Examples

## Not run: 

# Create the object by calling reactiveVal
r <- reactiveVal()

# Set the value by calling with an argument
r(10)

# Read the value by calling without arguments
r()


## End(Not run)

## Only run examples in interactive R sessions
if (interactive()) {

ui <- fluidPage(
  actionButton("minus", "-1"),
  actionButton("plus", "+1"),
  br(),
  textOutput("value")
)

# The comments below show the equivalent logic using reactiveValues()
server <- function(input, output, session) {
  value <- reactiveVal(0)       # rv <- reactiveValues(value = 0)

  observeEvent(input$minus, {
    newValue <- value() - 1     # newValue <- rv$value - 1
    value(newValue)             # rv$value <- newValue
  })

  observeEvent(input$plus, {
    newValue <- value() + 1     # newValue <- rv$value + 1
    value(newValue)             # rv$value <- newValue
  })

  output$value <- renderText({
    value()                     # rv$value
  })
}

shinyApp(ui, server)

}

Create an object for storing reactive values

Description

This function returns an object for storing reactive values. It is similar to a list, but with special capabilities for reactive programming. When you read a value from it, the calling reactive expression takes a reactive dependency on that value, and when you write to it, it notifies any reactive functions that depend on that value. Note that values taken from the reactiveValues object are reactive, but the reactiveValues object itself is not.

Usage

reactiveValues(...)

Arguments

See Also

isolate() and is.reactivevalues().

Examples

# Create the object with no values
values <- reactiveValues()

# Assign values to 'a' and 'b'
values$a <- 3
values[['b']] <- 4

## Not run: 
# From within a reactive context, you can access values with:
values$a
values[['a']]

## End(Not run)

# If not in a reactive context (e.g., at the console), you can use isolate()
# to retrieve the value:
isolate(values$a)
isolate(values[['a']])

# Set values upon creation
values <- reactiveValues(a = 1, b = 2)
isolate(values$a)

Convert a reactivevalues object to a list

Description

This function does something similar to what you might want or expect base::as.list() to do. The difference is that the calling context will take dependencies on every object in the reactivevalues object. To avoid taking dependencies on all the objects, you can wrap the call with isolate().

Usage

reactiveValuesToList(x, all.names = FALSE)

Arguments

Examples

values <- reactiveValues(a = 1)
## Not run: 
reactiveValuesToList(values)

## End(Not run)

# To get the objects without taking dependencies on them, use isolate().
# isolate() can also be used when calling from outside a reactive context (e.g.
# at the console)
isolate(reactiveValuesToList(values))

Reactive Log Visualizer

Description

Provides an interactive browser-based tool for visualizing reactive dependencies and execution in your application.

Usage

reactlog()

reactlogShow(time = TRUE)

reactlogReset()

reactlogAddMark(session = getDefaultReactiveDomain())

Arguments

Details

To use the reactive log visualizer, start with a fresh R session and run the command reactlog::reactlog_enable(); then launch your application in the usual way (e.g. using runApp()). At any time you can hit Ctrl+F3 (or for Mac users, Command+F3) in your web browser to launch the reactive log visualization.

The reactive log visualization only includes reactive activity up until the time the report was loaded. If you want to see more recent activity, refresh the browser.

Note that Shiny does not distinguish between reactive dependencies that "belong" to one Shiny user session versus another, so the visualization will include all reactive activity that has taken place in the process, not just for a particular application or session.

As an alternative to pressing Ctrl/Command+F3–for example, if you are using reactives outside of the context of a Shiny application–you can run the reactlogShow function, which will generate the reactive log visualization as a static HTML file and launch it in your default browser. In this case, refreshing your browser will not load new activity into the report; you will need to call reactlogShow() explicitly.

For security and performance reasons, do not enable options(shiny.reactlog=TRUE) (or reactlog::reactlog_enable()) in production environments. When the option is enabled, it's possible for any user of your app to see at least some of the source code of your reactive expressions and observers. In addition, reactlog should be considered a memory leak as it will constantly grow and will never reset until the R session is restarted.

Functions

• reactlog(): Return a list of reactive information. Can be used in conjunction with reactlog::reactlog_show to later display the reactlog graph.

• reactlogShow(): Display a full reactlog graph for all sessions.

• reactlogReset(): Resets the entire reactlog stack. Useful for debugging and removing all prior reactive history.

• reactlogAddMark(): Adds "mark" entry into the reactlog stack. This is useful for programmatically adding a marked entry in the reactlog, rather than using your keyboard's key combination.

  For example, we can mark the reactlog at the beginning of an observeEvent's calculation:

  observeEvent(input$my_event_trigger, {
    # Add a mark in the reactlog
    reactlogAddMark()
    # Run your regular event reaction code here...
    ....
  })
  

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

fastmap

is.key_missing, key_missing

htmltools

a, br, code, div, em, h1, h2, h3, h4, h5, h6, hr, HTML, htmlTemplate, img, includeCSS, includeHTML, includeMarkdown, includeScript, includeText, is.singleton, p, pre, singleton, span, strong, suppressDependencies, tag, tagAppendAttributes, tagAppendChild, tagAppendChildren, tagGetAttribute, tagHasAttribute, tagList, tags, tagSetChildren, validateCssUnit, withTags