Input controls

Each input control on a page is created by calling a Python function. All such functions take the same first two string arguments:

Note that many inputs take additional arguments. For example, an input_checkbox lets you indicate if it should start checked or not.

In the section below we’ll show the most common input objects. If you’re curious to learn more, see the API Reference on UI Inputs (for example, here’s the page for input_checkbox())

Input examples

Note

In these UI examples there’s no server logic, so we’re just using None instead of a server function.

Number inputs

ui.input_numeric creates a text box where a number (integer or real) can be entered, plus up/down buttons. This is most useful when you want the user to be able to enter an exact value.

ui.input_slider creates a slider. Compared to a numeric input, a slider makes it easier to scrub back and forth between values, so it may be more appropriate when the user does not have an exact value in mind to start with. You can also provide more restrictions on the possible values, as the min, max, and step size are all strictly enforced.

ui.input_slider can also be used to select a range of values. To do so, pass a tuple of two numbers as the value argument instead of a single number.

#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 300

from shiny import ui, App

app_ui = ui.page_fluid(
    ui.input_numeric("x1", "Number", value=10),
    ui.input_slider("x2", "Slider", value=10, min=0, max=20),
    ui.input_slider("x3", "Range slider", value=(6, 14), min=0, max=20)
)

app = App(app_ui, None)

Text inputs

Shiny includes three inputs for inputting string values.

Use ui.input_text for shorter, single-line values.

ui.input_text_area displays multiple lines, soft-wraps the text, and lets the user include line breaks, so is more appropriate for longer runs of text or multiple paragraphs.

ui.input_password is for passwords and other values that should not be displayed in the clear. (Note that Shiny does not apply any encryption to the password, so if your app involves passing sensitive information, make sure your deployed app uses https, not http, connections.)

#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 300

from shiny import ui, App

app_ui = ui.page_fluid(
    ui.input_text("x1", "Text", placeholder="Enter text"),
    ui.input_text_area("x2", "Text area", placeholder="Enter text"),
    ui.input_password ("x3", "Password", placeholder="Enter password"),
)

app = App(app_ui, None)

Selection inputs

ui.input_selectize and ui.input_select are useful for letting the user select from a list of values. You can choose whether the user can select multiple values or not, using the multiple argument. The difference between the two functions is that ui.input_selectize uses the Selectize JavaScript library, while ui.input_select inserts a standard HTML <select> tag. For most apps, we recommend ui.input_selectize for its better all-around usability, especially when multiple=True.

#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 450

from shiny import ui, App
import re

# A list of Python's built-in functions
choices = list(filter(lambda x: re.match(r'[a-z].*', x), dir(__builtins__)))

app_ui = ui.page_fluid(
    ui.input_selectize("x1", "Selectize (single)", choices),
    ui.input_selectize("x2", "Selectize (multiple)", choices, multiple = True),
    ui.input_select("x3", "Select (single)", choices),
    ui.input_select("x4", "Select (multiple)", choices, multiple = True),
)

app = App(app_ui, None)

ui.input_radio_buttons and ui.input_checkbox_group are useful for cases where you want the choices to always be displayed. Radio buttons force the user to choose one and only one option, while checkbox groups allow zero, one, or multiple choices to be selected.

#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 300

from shiny import ui, App

choices = {"a": "Choice A", "b": "Choice B", "c": "Choice C"}

app_ui = ui.page_fluid(
    ui.input_radio_buttons("x1", "Radio buttons", choices),
    ui.input_checkbox_group("x2", "Checkbox group", choices),
)

app = App(app_ui, None)

Toggle inputs

Toggles allow the user to specify whether something is true/false (or on/off, enabled/disabled, included/excluded, etc.).

ui.input_checkbox shows a simple checkbox, while ui.input_switch shows a toggle switch. These are functionally identical, but by convention, checkboxes should be used when part of a form that has a Submit or Continue button, while toggle switches should be used when they take immediate effect.

#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 125

from shiny import ui, App

app_ui = ui.page_fluid(
    ui.input_checkbox("x1", "Checkbox"),
    ui.input_switch("x2", "Switch")
)

app = App(app_ui, None)

Date inputs

ui.input_date lets the user specify a date, either interactively or by typing it in. ui.input_date_range is similar, but for cases where a start and end date are needed.

#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 300

from shiny import ui, App

app_ui = ui.page_fluid(
    ui.input_date("x1", "Date input"),
    ui.input_date_range("x2", "Date range input"),
)

app = App(app_ui, None)

Action inputs

ui.input_action_button and ui.input_action_link let the user invoke specific actions on the server side. (See Handling events for an introduction to using buttons and links.)

Use ui.input_action_button for actions that feels effectual: recalculating, fetching new data, applying settings, etc. Add class_="btn-primary" to highlight important actions (like Submit or Continue), and class_="btn-danger" to highlight dangerous actions (like Delete).

Use ui.input_action_link for actions that feel more like navigation, like exposing a new UI panel, navigating through paginated results, or bringing up a modal dialog.

#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 300

from shiny import ui, App

app_ui = ui.page_fluid(
    ui.p(ui.input_action_button("x1", "Action button")),
    ui.p(ui.input_action_button("x2", "Action button", class_="btn-primary")),
    ui.p(ui.input_action_link("x3", "Action link")),
)

app = App(app_ui, None)