Skip to main content

Extending the RStudio IDE with the Viewer Pane

Ian Pylvainen
  • Updated

The RStudio IDE includes a Viewer pane that can be used to view local web content. For example, web graphics generated using packages like googleVis, htmlwidgets, and rCharts, or even a local web application created using Shiny, Rook, or OpenCPU.

Note that the Viewer pane can only be used for local web content. This content can either be static HTML files written to the session temporary directory (i.e., files with paths generated by the tempfile function) or a locally run web application. For example, to display generated HTML content you would use code like this:

tempDir <- tempfile()
dir.create(tempDir)
htmlFile <- file.path(tempDir, "index.html")
# (code to write some content to the file)
viewer <- getOption("viewer")
viewer(htmlFile)

To display a local web application you would use code like this:

viewer <- getOption("viewer")
viewer("http://localhost:8000")

Invoking the Viewer

Local web content is displayed in the Viewer pane by accessing the RStudio viewer function definition via getOption("viewer")

This approach is front-end agnostic (other IDEs could define this option for alternative implementations of an internal viewer) and allows the user to override the default behavior if need be. For example, a package could use the following code to show content in the viewer when it's available but default back to the system browser when it's not:

viewer <- getOption("viewer")
if (!is.null(viewer))
  viewer("http://localhost:8100")
else
  utils::browseURL("http://localhost:8100")

Viewer Pane Height

If the web content or application you are displaying benefits from a minimum height (or would even like to occupy as much height as possible) then you can use the optional height parameter of the viewer function to request a given height. The default behavior if no height is requested is use the existing height of the Viewer pane. For example, to request a minimum height of 500 pixels you could use code like this:

viewer("http://localhost:8100", height = 500)

When requesting a minimum height there are a couple of considerations to keep in mind:

  • The request may or may not be satisfied. This is because RStudio applies the constraint that the resizing of the Viewer pane doesn't leave any other panes with a height of less than 160 pixels.
  • You should be very conservative when requesting a minimum height, as leaving users in control of pane layout is in general a better experience. When in doubt, it's better to request less height unless your content absolutely requires more vertical space.

It's also possible to request that the Viewer pane be maximized. You do this by passing "maximize" as the height parameter. Note that this value should only be specified in cases where maximum vertical space is essential, as it will result in one of the user's other panes being hidden.

Viewer Detection

When a page is displayed within the Viewer it's possible that the user will choose to pop it out into a standalone browser window. When rendering inside a standard browser you may want to make different choices about how content is laid out or scaled. Web pages can detect that they are running inside the Viewer pane by looking for the viewer_pane query parameter, which is automatically injected into URLs when they are shown in the Viewer. For example, the following URL:

http://localhost:8100

When rendered in the Viewer pane is transformed to:

http://localhost:8100?viewer_pane=1

We strongly recommended that callers take advantage of this to automatically scale their content to the current size of the Viewer pane, which will provide a good user experience. For example, re-render a JavaScript plot with new dimensions when the size of the pane changes.

Running Shiny Applications

It's possible to run Shiny applications within the Viewer pane by using the launch.browser parameter of the Shiny runApp function. Note however that this will only work with the shiny package version 0.8 or later and the httpuv package version 1.2 or later. To install the latest versions of these packages:

install.packages("httpuv")
install.packages("shiny")

Once you've ensured that you are running the latest versions of these packages you can run a Shiny application within the Viewer pane with code like this:

runApp("MyAppDir", launch.browser = rstudioapi::viewer)

Related articles