Customize your UI with HTML
By: Garrett Grolemund, Joe Cheng, and Mine Cetinkaya-Rundel
In this article, you will learn how to supplement the functions in your UI with raw HTML to create highly customized Shiny apps. You do not need to know HTML to use Shiny, but if you do, you can use the methods in this article to enhance your app.
The user-interface (UI) of a Shiny app is web document. Shiny developers can provide this document as an index.html file or assemble it from R code in their
The UI calls R functions that output HTML code. Shiny turns this code into a web app.
I will use the
01_hello app throughout this article as an example. You can access this app by running:
Many Shiny apps come with a
ui object that determines the layout of the app. The
ui object for
01_example looks like the following code:
The code creates this app:
ui object calls R functions that return HTML. In other words, Shiny lets you generate HTML with R. This is why you do not need to know HTML to use Shiny.
You can see that the functions in the
ui object definition return HTML if you run them.
fluidPage returns a chunk of HTML as does every function inside of
fluidPage. For example, the following code returns the HTML output in the comments below.
In R terminology, the output is a list of character strings with a special class that tells Shiny the contents contain HTML.
Shiny’s UI functions are sufficient for creating most Shiny apps. In a large majority of your Shiny apps, you will probably never think of using anything more complicated. However in some apps, you may want to add custom HTML that is not provided by the usual Shiny functions. You can do this by passing HTML tags with the
shiny::tags is a list of 110 functions. Each function builds a specific HTML tag. If you are familiar with HTML, you will recognize these tags by their names. You can learn what the most common tags do in the Shiny HTML tags glossary.
To create a tag, run an element of
tags as a function. To create a div tag, you can run:
You can call some of the most popular tags with helper functions (that wrap the appropriate
tags functions). For example, the helper function
code calls the tags$code and creates text formatted as computer code. The helper functions that can call their equivalent tags without using the tag syntex (tags$) are:
The names of other tags functions conflict with the names of native R functions, so you will need to call them with the
tags$ syntax. For example, to embed a plug-in or third party application call it with
Every tag function will treat its arguments in a special way: it will treat named arguments as HTML attributes and unnamed arguments as HTML children.
A tag function will use each named argument to add an HTML attribute to the tag. The argument name becomes the attribute name, and the argument value becomes the attribute value. So for example, if you want to create a div with a class attribute, use:
To add an attribute without a value, set the attribute to NA:
Each tag function will add unnamed arguments to your tag as HTML children. This addition lets you nest tags inside of each other (just as in HTML).
You can save typing by wrapping your HTML objects with
withTags is similar to R’s regular
with function. R will lookup each tag function mentioned inside
withTags in the
tags object, even if you do not specify
Once you have a complete tag, you can add it directly to your app’s UI object. For example, you could add the tag above to the
ui object of
Your updated app will contain the new HTML element.
Conditional attributes and children
If you set an argument of a tag function to NULL, the argument will not appear in the HTML output. NULL gives you a way to build attributes and children that will appear only under certain conditions.
You can pass a list of children to a tag with R’s list function. The tag function will add each element of the list as a child of the tag.
You cannot put raw HTML directly into a tag or UI object. Shiny will treat raw HTML as a character string, adding HTML as text to your UI document.
To add raw HTML, use the
HTML takes a character string and returns it as HTML (a special class of object in Shiny).
Shiny will assume that the code you pass to
HTML is correctly written HTML. Be sure to double check it.
It is a bad idea to pass an input object to
This allows the user to add their own HTML to your app, which creates a security vulnerability. What you user enters could be added to the web document or seen by other users, which might break the app. In the worse case scenario, a user may try to deploy malicious Cross Site Scripting (XSS), an undesirable security vulnerability.
You can use HTML to customize your Shiny apps. Every Shiny app is built on an HTML document that creates the apps’ user interface. Usually, Shiny developers create this document by building the
ui object with R functions that build HTML output. However, you can supply HTML output directly with Shiny’s
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.