RStudio 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()
htmlFile <- file.path(tempDir, "index.html")
# (code to write some content to the file)
viewer <- getOption("viewer")
To display a local web application you would use code like this:
viewer <- getOption("viewer")
Invoking the Viewer
Local web content is displayed in the Viewer pane by accessing the RStudio
viewer function definition via
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.
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:
When rendered in the Viewer pane is transformed to:
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:
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)