API Reference Intro#

This website documents the public API of Shiny (for Python). See the Getting Started tutorial for a more approachable introduction to the API. The left-hand sidebar lists the full public API, without any grouping, but the sections below (linked to the right-hand sidebar) break it into semantically similar groups. Most of the reference pages include a live example app at the bottom, or at least mention another page with a relevant example.

We’ve intentionally designed Shiny’s API so that you can from shiny import * to get access to most of what you need for most apps without introducing an excessive amount of namespace pollution. Namely, it gives you:

  • User interface (UI/HTML) helpers, available via the ui subpackage.

    • To avoid clashing with this ui namespace when you do from shiny import *, you’ll want to name you UI object something else, like app_ui.

  • Reactive programming utilities, available via the reactive subpackage.

  • Decorators for rendering output, available via the render subpackage.

    • 3rd party packages that want to implement their own rendering functions are encouraged to use a @render_foo() naming convention so users may import with from mypkg import render_foo.

  • A handful of other things you’ll want for most apps (e.g., App, Module, etc).

  • If you’re using type checking, you’ll also want to use the Inputs, Outputs, and Session Classes to type the instances supplied to your server function, for example:

#| layout: vertical
from shiny import *

app_ui = ui.page_fluid(
  ui.input_slider("n", "Value of n", min=1, max=10, value=5),

def server(input: Inputs, output: Outputs, session: Session) -> None:
    def n2():
        return f"The value of n*2 is {input.n() * 2}"

app = App(app_ui, server)

API Reference#

Page containers#

Create a user interface page container.

ui.page_navbar(*args[, title, id, selected, ...])

Create a navbar with a navs bar and a title.

ui.page_fluid(*args[, title, lang])

Create a fluid page.

ui.page_fixed(*args[, title, lang])

Create a fixed page.

ui.page_bootstrap(*args[, title, lang])

Create a Bootstrap UI page container.

UI Layout#

Control the layout of multiple UI components.

ui.layout_sidebar(sidebar, main[, position])

Layout a sidebar and main area

ui.panel_sidebar(*args[, width])

Create a sidebar panel

ui.panel_main(*args[, width])

Create an main area panel

ui.column(width, *args[, offset])

Responsive row-column based layout

ui.row(*args, **kwargs)

Responsive row-column based layout

UI Inputs#

Create UI that prompts the user for input values or interaction.

ui.input_select(id, label, choices, *[, ...])

Create a select list that can be used to choose a single or multiple items from a list of values.

ui.input_selectize(id, label, choices, *[, ...])

Create a select list that can be used to choose a single or multiple items from a list of values.

ui.input_slider(id, label, min, max, value, *)

Constructs a slider widget to select a number, date, or date-time from a range.

ui.input_date(id, label, *[, value, min, ...])

Creates a text input which, when clicked on, brings up a calendar that the user can click on to select dates.

ui.input_date_range(id, label, *[, start, ...])

Creates a pair of text inputs which, when clicked on, bring up calendars that the user can click on to select dates.

ui.input_checkbox(id, label[, value, width])

Create a checkbox that can be used to specify logical values.

ui.input_checkbox_group(id, label, choices, *)

Create a group of checkboxes that can be used to toggle multiple choices independently.

ui.input_switch(id, label[, value, width])

Create a switch that can be used to specify logical values.

ui.input_radio_buttons(id, label, choices, *)

Create a set of radio buttons used to select an item from a list.

ui.input_numeric(id, label, value, *[, min, ...])

Create an input control for entry of numeric values.

ui.input_text(id, label[, value, width, ...])

Create an input control for entry of text values

ui.input_text_area(id, label[, value, ...])

Create a textarea input control for entry of unstructured text values.

ui.input_password(id, label[, value, width, ...])

Create an password control for entry of passwords.

ui.input_action_button(id, label, *[, icon, ...])

Creates an action button whose value is initially zero, and increments by one each time it is pressed.

ui.input_action_link(id, label, *[, icon])

Creates a link whose value is initially zero, and increments by one each time it is pressed.

Update inputs#

Programmatically update input values

ui.update_select(id, *[, label, choices, ...])

Change the value of a select input on the client.

ui.update_selectize(id, *[, label, choices, ...])

Change the value of a selectize.js powered input on the client.

ui.update_slider(id, *[, label, value, min, ...])

Change the value of a slider input on the client.

ui.update_date(id, *[, label, value, min, ...])

Change the value of a date input on the client.

ui.update_date_range(id, *[, label, start, ...])

Change the start and end values of a date range input on the client.

ui.update_checkbox(id, *[, label, value, ...])

Change the value of a checkbox input on the client.

ui.update_checkbox_group(id, *[, label, ...])

Change the value of a checkbox group input on the client.

ui.update_switch(id, *[, label, value, session])

Change the value of a switch input on the client.

ui.update_radio_buttons(id, *[, label, ...])

Change the value of a radio input on the client.

ui.update_numeric(id, *[, label, value, ...])

Change the value of a number input on the client.

ui.update_text(id, *[, label, value, ...])

Change the value of a text input on the client.

ui.update_text_area(id, *[, label, value, ...])

Change the value of a text input on the client.

ui.update_navs(id[, selected, session])

Change the value of a navs container on the client.

UI panels#

Visually group together a section of UI components.

ui.panel_absolute(*args[, top, left, right, ...])

Create a panel of absolutely positioned content.

ui.panel_fixed(*args, **kwargs)

Create a panel of absolutely positioned content.

ui.panel_conditional(condition, *args, **kwargs)

Create a conditional panel

ui.panel_title(title[, window_title])

Create title(s) for the application.

ui.panel_well(*args, **kwargs)

Create a well panel

Uploads & downloads#

Allows users to upload and download files.

ui.input_file(id, label, *[, multiple, ...])

Create a file upload control that can be used to upload one or more files.

ui.download_button(id, label[, icon, width])

Create a download button

Custom UI#

Lower-level UI functions for creating custom HTML/CSS/JS.


Mark a string as raw HTML.


Create an HTML tag list (i.e., a fragment of HTML)


Functions for creating HTML tags.

ui.markdown(text, *[, render_func])

Convert a string of markdown to ui.HTML().

ui.insert_ui(ui, selector[, where, ...])

Insert UI objects

ui.remove_ui(selector[, multiple, ...])

Remove UI objects

Rendering outputs#

UI (output_*()) and server (render)ing functions for generating content server-side.

ui.output_plot(id[, width, height, inline])

Create a output container for a static plot.


Reactively render a plot object as an HTML image.

ui.output_image(id[, width, height, inline])

Create a output container for a static image.


Reactively render a image file as an HTML image.

ui.output_text(id[, inline, container])

Create a output container for some text.

ui.output_text_verbatim(id[, placeholder])

Create a output container for some text.


Reactively render text.

ui.output_ui(id[, inline, container])

Create a output container for a UI (i.e., HTML) element.


Reactively render HTML content.

Reactive programming#

Reactive programming facilities for Python.


Mark a function as a reactive calculation.


Mark a function as a reactive side effect.


Create a reactive value


Create a non-reactive scope within a reactive scope.

reactive.invalidate_later(delay, *[, session])

Scheduled Invalidation


Run any pending invalidations (i.e., flush the reactive environment).

reactive.poll(poll_func[, interval_secs, ...])

Create a reactive polling object.

reactive.file_reader(filepath[, ...])

Create a reactive file reader.

event(*args, **kwargs)


Create and run applications#

Create, run, stop, and hook into the lifecycle of Shiny applications.

run_app([app, host, port, autoreload_port, ...])

Starts a Shiny app.

App(ui, server, *[, static_assets, debug])

Create a Shiny app instance.

Inputs(values[, ns])

A class representing Shiny input values.

Outputs(session, ns, effects, ...)

A class representing Shiny output definitions.

Session(app, id, conn[, debug])

A class representing a user session.

Display messages#

Display messages to the user.

ui.help_text(*args, **kwargs)

Create a help text element

ui.notification_show(ui[, action, duration, ...])

Show a notification to the user.

ui.notification_remove(id[, session])

Remove a notification.

ui.modal(*args[, title, footer, size, ...])

Creates the UI for a modal dialog, using Bootstrap's modal class.

ui.modal_show(modal[, session])

Show a modal dialog.


Remove a modal dialog.

ui.modal_button(label[, icon])

Creates a button that will dismiss a modal() (useful when customising the footer of modal()).

ui.Progress([min, max, session])

Initialize a progress bar.

Error validation#

Control how errors are shown to the user.

req(*args[, cancel_output])

Throw a silent exception for falsey values.


Throw a silent exception.


Throw a silent exception and don't clear output


Throw a safe exception.


Control application complexity by namespacing UI and server code.



Callable[[str, ~P], ~R]



Callable[[str, ~P], ~R]

Type hints#

Classes for type hinting input/output values.

types.FileInfo(_typename[, _fields])

Information about a file upload.

types.ImgData(_typename[, _fields])

Return type for image().

Developer facing tools#

Tools for Shiny developers.


Get the current user session.


Raise an exception if no Shiny session is currently active.


Context manager for current session.


Get the current reactive context.


Manage Shiny input handlers.