Add control widgets

This lesson will show you how to add control widgets to your Shiny apps. What’s a widget? A web element that your users can interact with. Widgets provide a way for your users to send messages to the Shiny app.

Shiny widgets collect a value from your user. When a user changes the widget, the value will change as well. This sets up opportunities that we’ll explore in Lesson 4.

Control widgets

The set of basic widgets you can use in Shiny. Includes buttons, single checkbox, checkbox, date input, date range, file input, help text, numeric input, radio buttons, select box, sliders, text input

Shiny comes with a family of pre-built widgets, each created with a transparently named R function. For example, Shiny provides a function named actionButton that creates an Action Button and a function named sliderInput that creates a slider bar.

The standard Shiny widgets are:

function widget
actionButton Action Button
checkboxGroupInput A group of check boxes
checkboxInput A single check box
dateInput A calendar to aid date selection
dateRangeInput A pair of calendars for selecting a date range
fileInput A file upload control wizard
helpText Help text that can be added to an input form
numericInput A field to enter numbers
radioButtons A set of radio buttons
selectInput A box with choices to select from
sliderInput A slider bar
submitButton A submit button
textInput A field to enter text

Some of these widgets are built using the Twitter Bootstrap project, a popular open source framework for building user interfaces.

Adding widgets

You can add widgets to your web page in the same way that you added other types of HTML content in Lesson 2.

Each widget function requires several arguments. The first two arguments for each widget are

  • a name for the widget: The user will not see this name, but you can use it to access the widget’s value. The name should be a character string.

  • a label: This label will appear with the widget in your app. It should be a character string, but it can be an empty string "".

In this example, the name is “action” and the label is “Action”: actionButton("action", label = "Action")

The remaining arguments vary from widget to widget, depending on what the widget needs to do its job. They include things like initial values, ranges, and increments. You can find the exact arguments needed by a widget on the widget function’s help page, (e.g., ?selectInput).

The app.R script below makes the app pictured above. Change your own App-1/app.R script to match it, and then launch the app (runApp("App-1"), select Run App, or use shortcuts).

Play with each widget to get a feel for what it does. Experiment with changing the values of the widget functions and observe the effects. If you are interested in the layout scheme for this Shiny app, read the description in the application layout guide. This lesson will not cover this slightly more complicated layout scheme, but it is interesting to note what it does.

library(shiny)

# Define UI ----
ui <- page_fluid(
  titlePanel("Basic widgets"),
  layout_columns(
    col_width = 3,
    card(
      card_header("Buttons"),
      actionButton("action", "Action"),
      submitButton("Submit")
    ),
    card(
      card_header("Single checkbox"),
      checkboxInput("checkbox", "Choice A", value = TRUE)
    ),
    card(
      card_header("Checkbox group"),
      checkboxGroupInput(
        "checkGroup",
        "Select all that apply",
        choices = list("Choice 1" = 1, "Choice 2" = 2, "Choice 3" = 3),
        selected = 1
      )
    ),
    card(
      card_header("Date input"),
      dateInput("date", "Select date", value = "2014-01-01")
    ),
    card(
      card_header("Date range input"),
      dateRangeInput("dates", "Select dates")
    ),
    card(
      card_header("File input"),
      fileInput("file", label = NULL)
    ),
    card(
      card_header("Help text"),
      helpText(
        "Note: help text isn't a true widget,",
        "but it provides an easy way to add text to",
        "accompany other widgets."
      )
    ),
    card(
      card_header("Numeric input"),
      numericInput("num", "Input number", value = 1)
    ),
    card(
      card_header("Radio buttons"),
      radioButtons(
        "radio",
        "Select option",
        choices = list("Choice 1" = 1, "Choice 2" = 2, "Choice 3" = 3),
        selected = 1
      )
    ),
    card(
      card_header("Select box"),
      selectInput(
        "select",
        "Select option",
        choices = list("Choice 1" = 1, "Choice 2" = 2, "Choice 3" = 3),
        selected = 1
      )
    ),
    card(
      card_header("Sliders"),
      sliderInput(
        "slider1",
        "Set value",
        min = 0,
        max = 100,
        value = 50
      ),
      sliderInput(
        "slider2",
        "Set value range",
        min = 0,
        max = 100,
        value = c(25, 75)
      )
    ),
    card(
      card_header("Text input"),
      textInput("text", label = NULL, value = "Enter text...")
    )
  )
)

# Define server logic ----
server <- function(input, output) {

}

# Run the app ----
shinyApp(ui = ui, server = server)

Your turn

Rewrite your ui to create the user interface displayed below. Notice that this Shiny app uses a basic Shiny layout (no columns) and contains three of the widgets pictured above. The other values of the select box are shown below the image of the app.

Left section of a Shiny app for censusVis

Select box widget for censusVis app

Model Answer

Be sure your ui is identical to the one displayed below before you move on. You will use the script in Lesson 4 and Lesson 5, as part of an app that visualizes census data.

In particular, make sure that your select box widget is named “var”, and your slider widget is named “range”.

Also notice that the slider widget has two values, not one.

ui <- page_sidebar(
  title = "censusVis",
  sidebar = sidebar(
    helpText(
      "Create demographic maps with information from the 2010 US Census."
    ),
    selectInput(
      "var",
      label = "Choose a variable to display",
      choices = 
        list(
          "Percent White", 
          "Percent Black", 
          "Percent Hispanic", 
          "Percent Asian"
        ),
      selected = "Percent White"
    ),
    sliderInput("range",
                label = "Range of interest:",
                min = 0, max = 100, value = c(0, 100))
  )
)

Recap

It is easy to add fully functional widgets to your Shiny app.

  • Shiny provides a family of functions to create these widgets.

  • Each function requires a name and a label.

  • Some widgets need specific instructions to do their jobs.

  • You add widgets to your Shiny app just like you added other types of HTML content (see Lesson 2)

Go Further

The Shiny Widgets Gallery provides templates that you can use to quickly add widgets to your Shiny apps.

To use a template, visit the gallery. The gallery displays each of Shiny’s widgets, and demonstrates how the widgets’ values change in response to your input.

Shiny widgets gallery

Select the widget that you want and click the “See Code” button below the widget. The gallery will take you to an example app that describes the widget. To use the widget, copy and paste the code in the example’s app.R file to your app.R file.

Individual widget of a checkbox group

In Lesson 4, you will learn how to connect widgets to reactive output, objects that update themselves whenever your user changes a widget.