session: Session object

In shiny: Web Application Framework for R

Session object

Description

Shiny server functions can optionally include session as a parameter (e.g. ⁠function(input, output, session)⁠). The session object is an environment that can be used to access information and functionality relating to the session. The following list describes the items available in the environment; they can be accessed using the $ operator (for example, session$clientData$url_search).

Value

allowReconnect(value)	If value is TRUE and run in a hosting environment (Shiny Server or Connect) with reconnections enabled, then when the session ends due to the network connection closing, the client will attempt to reconnect to the server. If a reconnection is successful, the browser will send all the current input values to the new session on the server, and the server will recalculate any outputs and send them back to the client. If value is FALSE, reconnections will be disabled (this is the default state). If "force", then the client browser will always attempt to reconnect. The only reason to use "force" is for testing on a local connection (without Shiny Server or Connect).
clientData	A reactiveValues() object that contains information about the client. pixelratio reports the "device pixel ratio" from the web browser, or 1 if none is reported. The value is 2 for Apple Retina displays. singletons - for internal use url_protocol, url_hostname, url_port, url_pathname, url_search, url_hash_initial and url_hash can be used to get the components of the URL that was requested by the browser to load the Shiny app page. These values are from the browser's perspective, so neither HTTP proxies nor Shiny Server will affect these values. The url_search value may be used with parseQueryString() to access query string parameters. clientData also contains information about each output. output_outputId_width and output_outputId_height give the dimensions (using offsetWidth and offsetHeight) of the DOM element that is bound to outputId, and output_outputId_hidden is a logical that indicates whether the element is hidden. These values may be NULL if the output is not bound.
input	The session's input object (the same as is passed into the Shiny server function as an argument).
isClosed()	A function that returns TRUE if the client has disconnected.
ns(id)	Server-side version of ns <- NS(id). If bare IDs need to be explicitly namespaced for the current module, session$ns("name") will return the fully-qualified ID.
onDestroy(callback)	Registers a callback to be invoked when the session scope ends. Returns a function that can be called to unregister the callback. For the root session, callbacks are invoked when the session closes, after session$onEnded() callbacks. Note, session$destroy() is not allowed for root sessions. For module session proxies, callbacks are invoked when session$destroy() is called.
destroy(id = NULL)	Destroys a module session scope (and any descendant scopes) by invoking all registered onDestroy() callbacks. This includes cleaning up all reactive values, observers, and reactive expressions created within that scope (and any descendant scopes). Called with no id on a module session proxy (e.g. the session inside moduleServer()), it destroys that module's own scope. Called with an id, it destroys the child module scope of that id — this is how a parent tears down a module it added, using the same id it used to insert the UI: removeUI(selector = "#editor") session$destroy("editor") On the root session an id is required; session$destroy() with no id is an error (the root session is torn down via close()).
onEnded(callback)	Synonym for onSessionEnded.
onFlush(func, once=TRUE)	Registers a function to be called before the next time (if once=TRUE) or every time (if once=FALSE) Shiny flushes the reactive system. Returns a function that can be called with no arguments to cancel the registration.
onFlushed(func, once=TRUE)	Registers a function to be called after the next time (if once=TRUE) or every time (if once=FALSE) Shiny flushes the reactive system. Returns a function that can be called with no arguments to cancel the registration.
onSessionEnded(callback)	Registers a function to be called after the client has disconnected. Returns a function that can be called with no arguments to cancel the registration.
output	The session's output object (the same as is passed into the Shiny server function as an argument).
reactlog	For internal use.
registerDataObj(name, data, filterFunc)	Publishes any R object as a URL endpoint that is unique to this session. name must be a single element character vector; it will be used to form part of the URL. filterFunc must be a function that takes two arguments: data (the value that was passed into registerDataObj) and req (an environment that implements the Rook specification for HTTP requests). filterFunc will be called with these values whenever an HTTP request is made to the URL endpoint. The return value of filterFunc should be a Rook-style response.
reload()	The equivalent of hitting the browser's Reload button. Only works if the session is actually connected.
request	An environment that implements the Rook specification for HTTP requests. This is the request that was used to initiate the websocket connection (as opposed to the request that downloaded the web page for the app).
userData	An environment for app authors and module/package authors to store whatever session-specific data they want.
user	User's log-in information. Useful for identifying users on hosted platforms such as RStudio Connect and Shiny Server.
groups	The user's relevant group information. Useful for determining what privileges the user should or shouldn't have.
resetBrush(brushId)	Resets/clears the brush with the given brushId, if it exists on any imageOutput or plotOutput in the app.
sendCustomMessage(type, message)	Sends a custom message to the web page. type must be a single-element character vector giving the type of message, while message can be any jsonlite-encodable value. Custom messages have no meaning to Shiny itself; they are used solely to convey information to custom JavaScript logic in the browser. You can do this by adding JavaScript code to the browser that calls Shiny.addCustomMessageHandler(type, function(message){...}) as the page loads; the function you provide to addCustomMessageHandler will be invoked each time sendCustomMessage is called on the server.
sendBinaryMessage(type, message)	Similar to sendCustomMessage, but the message must be a raw vector and the registration method on the client is Shiny.addBinaryMessageHandler(type, function(message){...}). The message argument on the client will be a DataView.
sendInputMessage(inputId, message)	Sends a message to an input on the session's client web page; if the input is present and bound on the page at the time the message is received, then the input binding object's receiveMessage(el, message) method will be called. sendInputMessage should generally not be called directly from Shiny apps, but through friendlier wrapper functions like updateTextInput().
setBookmarkExclude(names)	Set input names to be excluded from bookmarking.
getBookmarkExclude()	Returns the set of input names to be excluded from bookmarking.
onBookmark(fun)	Registers a function that will be called just before bookmarking state.
onBookmarked(fun)	Registers a function that will be called just after bookmarking state.
onRestore(fun)	Registers a function that will be called when a session is restored, before all other reactives, observers, and render functions are run.
onRestored(fun)	Registers a function that will be called when a session is restored, after all other reactives, observers, and render functions are run.
doBookmark()	Do bookmarking and invoke the onBookmark and onBookmarked callback functions.
exportTestValues()	Registers expressions for export in test mode, available at the test snapshot URL.
getTestSnapshotUrl(input=TRUE, output=TRUE, export=TRUE, format="json")	Returns a URL for the test snapshots. Only has an effect when the shiny.testmode option is set to TRUE. For the input, output, and export arguments, TRUE means to return all of these values. It is also possible to specify by name which values to return by providing a character vector, as in input=c("x", "y"). The format can be "rds" or "json".
setCurrentTheme(theme)	Sets the current bootstrapLib() theme, which updates the value of getCurrentTheme(), invalidates session$getCurrentTheme(), and calls function(s) registered with registerThemeDependency() with provided theme. If those function calls return htmltools::htmlDependency()s with stylesheets, then those stylesheets are "refreshed" (i.e., the new stylesheets are inserted on the page and the old ones are disabled and removed).
getCurrentTheme()	A reactive read of the current bootstrapLib() theme.

Destroying a module

Every reactive object (values, expressions, observers) is scoped to the session in which it was created. Destroying a module session tears down only the objects in that scope; the parent session and sibling modules are unaffected. This scoping is what makes modules safe to add and remove dynamically — without it, destroying one module could leak callbacks or invalidate reactive objects that belong to another part of the app.

The parent that inserted the module's UI under an id can tear it down by that same id, without the module having to hand anything back:

# In the parent server: insert, then later remove and destroy by id
observeEvent(input$add, {
  insertUI("#container", ui = myModuleUI("editor"))
  myModuleServer("editor")
})
observeEvent(input$remove, {
  removeUI(selector = "#editor")
  session$destroy("editor")
})

Inside the module, session$destroy() (with no id) destroys the module's own scope. A module can expose this as a handle for callers that need to trigger teardown from somewhere that doesn't have the parent session or id (see the data ownership section below for an example).

Module data ownership

The key rule: data that must outlive a module should live outside it. A reactive value created inside a module is destroyed with the module. A reactive value created in the caller's scope and passed in survives destruction.

Returning a reactive value from a module works when the module lives for the entire session. However, if you plan to call session$destroy(), the returned value will be destroyed and can no longer be read:

myModuleServer <- function(id) {
  moduleServer(id, function(input, output, session) {
    result <- reactiveVal(0)
    # ... update result ...
    list(result = result, destroy = session$destroy)
  })
}

mod <- myModuleServer("editor")
mod$destroy()
mod$result()
#> Error: Can't access reactive; its module session has been destroyed

Instead, pass a reactive value into the module. The value lives in the caller's scope and survives destruction:

myModuleServer <- function(id, result) {
  moduleServer(id, function(input, output, session) {
    observeEvent(input$save, {
      result(input$data)
    })
  })
}

# Caller creates and owns the value
saved_data <- reactiveVal(NULL)
myModuleServer("editor", result = saved_data)
# saved_data is still valid after the module is destroyed

See Also

moduleServer(), removeUI()

shiny documentation built on June 21, 2026, 5:07 p.m.