Package 'shiny'

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 [email protected] (ORCID)

Authors:

• Joe Cheng [email protected]

• JJ Allaire [email protected]

• Carson Sievert [email protected] (ORCID)

• Barret Schloerke [email protected] (ORCID)

• Yihui Xie [email protected]

• Jeff Allen

• Jonathan McPherson [email protected]

• 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.

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.

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")

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)

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())
  }
)

}

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.

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)
}

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.

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()

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)

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.

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

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)
}

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)
}

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.

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) { })
}

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)
}

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)

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.

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) { })
}

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) { })
}

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)
}

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

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.

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)

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)
}

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)

}

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())
    })
  }
)
}

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()

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)
}

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%;")
  )
)

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)

}

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) { })
}

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) { })
}

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) { })
}

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)
}

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
        )
      })
    }
  )
}

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)
      })
    }
  )
}

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.

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.")

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")
)

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"))
)

Description

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

Usage

inputPanel(...)

Arguments

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())