By: Winston Chang
In most cases, the best way to create a Shiny application’s user interface is to build it with R code, using functions like
div(), and so on. Sometimes, though, you may want to integrate Shiny with existing HTML, and starting with Shiny 0.13 (and htmltools 0.3), this can be done with the HTML templates. Templates can be used to generate complete web pages, and they can also be used to generate the HTML for components that are included in a Shiny app.
Complete web pages
To use an HTML template for the UI, first create an HTML file in your app directory, at the same level as the
app.R files (not in a
www/ subdirectory). Here’s an example template for a complete web page,
And here’s a corresponding
ui.R that uses the template:
Some things to notice:
The template is just plain HTML, except for the parts in
}}. The parts in those curly braces are R code which is evaluated when the template is processed.
headContent() must be placed in the
<head> section of the HTML, if this is a complete HTML page (as opposed to a component of a page, which we’ll discuss later). This tells Shiny that the various Shiny header code should be included here.
htmlTemplate() is called with the named arguments
slider. The values are used when evaluating the R code in the template.
Once processed, the HTML produced will look something like this. You can see where the Shiny head content was inserted, and similarly, the
sliderInput HTML code.
Evaluating code and passing variables
In the previous example, the double-curly braces in the template simply contain the names of variables,
slider. However, the R code blocks aren’t limited to simple names; any R code can be placed inside a code block. In the example below, we’ll put
sliderInput() directly in the template, and we’ll pass in an initial value to the
To process the template’s R code, the
htmlTemplate() function first creates a child environment of the global environment, populates it with variables that were passed in as arguments to the function (like
sliderValue), and then evaluates the template’s R code. This means that the template’s R code will also have access to any variables set in R’s global environment – but it’s not good practice to make use of global variables in the template; it’s better to pass values explicitly in the call to
NOTE: Only the last thing in a code block is included in the HTML output. This is because of how the code blocks are evaluated; only the last thing is returned. If you have a code block with multiple elements that you want in the HTML, you can split it into multiple code blocks, or put the elements together with
Including other web dependencies
In this example, the file
customlib.js would be expected to be in the
www/ subdirectory of the app, so that it could served to the client browser. You could also point to an absolute URL (starting with
https://) served from another host. This is useful for using popular libraries served from a CDN.
When you include a web dependency this way, there is a possibility that some Shiny code will pull in the same dependency. Imagine that your web page uses D3, so you include a
<script> tag for it, but then you also use an R component that pulls in a D3 dependency automatically, like d3heatmap.
<script> tag that you added, and once from
d3heatmap() automatically pulling it in:
This could cause problems in running the D3 code. To avoid having two copies of a library, use
suppressDependencies(). This will ensure that Shiny components won’t automatically pull in their own versions of web dependencies, and only the one that you manually added to the template will be used:
Using Bootstrap components
Some web components in Shiny require the Bootstrap web framework in order to display correctly. These include, for example,
Bootstrap is included automatically when a Shiny UI is created with
navbarPage(), and others. However, if you use an HTML template to generate the web page, using
headContent() will not include Bootstrap – it only includes Shiny’s basic web dependencies. In order to include Bootstrap, use
Templates for components
In the examples above, HTML templates were used to generate an entire web page. They can also be used for components that are included in a larger application. For example, you could have this
When using a template as a component, don’t include
headContent(), or a
<head> tag. Just include the HTML which you want to be inserted in the web page.
Using templates in packages
Packages can use HTML templates for components. If you have a package named
mypackage and have a template file in the package sources at
inst/templates/component.html, you can access that file with:
The package could contain a function that makes use of the template:
Someone using your package could call
myComponent("examplename") to put the component in their UI.
The example above use a template to generate a component, but the same strategy can be used to generate a complete web page.
If you have questions about this article or would like to discuss ideas presented here, please post on RStudio Community. Our developers monitor these forums and answer questions periodically. See help for more help with all things Shiny.