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 gives quick access to the full public API, and the table of contents below shows the same entries plus a brief summary for each. 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:

#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 400
## file: app.py
from shiny import *

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

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

app = App(app_ui, server)

Function reference

Page containers

Create a user interface page container.

ui.page_navbar Create a page with a navbar and a title.
ui.page_fluid Create a fluid page.
ui.page_fixed Create a fixed page.
ui.page_bootstrap Create a Bootstrap UI page container.

UI Layout

Control the layout of multiple UI components.

ui.layout_sidebar Layout a sidebar and main area
ui.panel_sidebar Create a sidebar panel
ui.panel_main Create an main area panel
ui.column Responsive row-column based layout
ui.row Responsive row-column based layout

UI Inputs

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

ui.input_select Create a select list that can be used to choose a single or multiple items from a
ui.input_selectize Create a select list that can be used to choose a single or multiple items from a
ui.input_slider Constructs a slider widget to select a number, date, or date-time from a range.
ui.input_date Creates a text input which, when clicked on, brings up a calendar that the user can
ui.input_date_range Creates a pair of text inputs which, when clicked on, bring up calendars that the
ui.input_checkbox Create a checkbox that can be used to specify logical values.
ui.input_checkbox_group Create a group of checkboxes that can be used to toggle multiple choices
ui.input_switch Create a switch that can be used to specify logical values. Similar to
ui.input_radio_buttons Create a set of radio buttons used to select an item from a list.
ui.input_numeric Create an input control for entry of numeric values.
ui.input_text Create an input control for entry of text values
ui.input_text_area Create a textarea input control for entry of unstructured text values.
ui.input_password Create an password control for entry of passwords.
ui.input_action_button Creates an action button whose value is initially zero, and increments by one each
ui.input_action_link Creates a link whose value is initially zero, and increments by one each time it is

Update inputs

Programmatically update input values.

ui.update_select Change the value of a select input on the client.
ui.update_selectize Change the value of a selectize.js powered input on the client.
ui.update_slider Change the value of a slider input on the client.
ui.update_date Change the value of a date input on the client.
ui.update_date_range Change the start and end values of a date range input on the client.
ui.update_checkbox Change the value of a checkbox input on the client.
ui.update_checkbox_group Change the value of a checkbox group input on the client.
ui.update_switch Change the value of a switch input on the client.
ui.update_radio_buttons Change the value of a radio input on the client.
ui.update_numeric Change the value of a number input on the client.
ui.update_text Change the value of a text input on the client.
ui.update_text_area Change the value of a text input on the client.
ui.update_navs Change the value of a navs container on the client.

UI panels

Visually group together a section of UI components.

ui.panel_absolute Create a panel of absolutely positioned content.
ui.panel_fixed Create a panel of absolutely positioned content.
ui.panel_conditional Create a conditional panel
ui.panel_title Create title(s) for the application.
ui.panel_well Create a well panel

Uploads & downloads

Allow users to upload and download files.

ui.input_file Create a file upload control that can be used to upload one or more files.
ui.download_button Create a download button

Custom UI

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

ui.HTML Mark a string as raw HTML. This will prevent the string from being escaped when
ui.TagList Create an HTML tag list (i.e., a fragment of HTML)
ui.tags Functions for creating HTML tags.
ui.markdown Convert a string of markdown to :func:ui.HTML.
ui.include_css Include a CSS file
ui.include_js Include a JavaScript file
ui.insert_ui Insert UI objects
ui.remove_ui Remove UI objects

Rendering outputs

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

ui.output_plot Create a output container for a static plot.
ui.output_image Create a output container for a static image.
ui.output_table Create a output container for a table.
ui.output_data_frame Create a output container for a data frame.
ui.output_text Create a output container for some text.
ui.output_text_verbatim Create a output container for some text.
ui.output_ui Create a output container for a UI (i.e., HTML) element.
render.plot Reactively render a plot object as an HTML image.
render.image Reactively render a image file as an HTML image.
render.table Reactively render a Pandas data frame object (or similar) as a basic HTML table.
render.text Reactively render text.
render.ui Reactively render HTML content.
render.data_frame Reactively render a Pandas data frame object (or similar) as a basic HTML table.
render.DataGrid Holds the data and options for a shiny.render.data_frame output, for a
render.DataTable Holds the data and options for a shiny.render.data_frame output, for a

Reactive programming

reactive.Calc Mark a function as a reactive calculation.
reactive.Effect Mark a function as a reactive side effect.
reactive.Value Create a reactive value.
reactive.event Mark a function to react only when an "event" occurs.
reactive.isolate Create a non-reactive scope within a reactive scope.
reactive.invalidate_later Scheduled Invalidation
reactive.flush Run any pending invalidations (i.e., flush the reactive environment).
reactive.poll Create a reactive polling object.
reactive.file_reader Create a reactive file reader.
reactive.lock A lock that should be held whenever manipulating the reactive graph.
req Throw a silent exception for falsy values.

Create and run applications

run_app Starts a Shiny app. Press Ctrl+C (or Ctrl+Break on Windows) to stop.
App Create a Shiny app instance.
Inputs A class representing Shiny input values.
Outputs A class representing Shiny output definitions.
Session A class representing a user session.

Display messages

ui.help_text Create a help text element
ui.notification_show Show a notification to the user.
ui.notification_remove Remove a notification.
ui.modal Creates the UI for a modal dialog, using Bootstrap's modal class. Modals are
ui.modal_show Show a modal dialog.
ui.modal_remove Remove a modal dialog.
ui.modal_button Creates a button that will dismiss a :func:modal (useful when customising the
ui.Progress Initialize a progress bar.

Modules

module.ui
module.server

Developer facing tools

session.get_current_session Get the current user session.
session.require_active_session Raise an exception if no Shiny session is currently active.
session.session_context Context manager for current session.
reactive.get_current_context Get the current reactive context.
input_handler.input_handlers Manage Shiny input handlers.

Types

Miscellaneous types
Tag types
Exception types

Experimental

These methods are under consideration and are considered unstable. However, if there is a method you are excited about, please let us know!

Sidebar Sidebar layouts allow users to easily access filters, settings, and other inputs alongside interactive features they control.
Card Cards are a common organizing unit for modern user interfaces (UI). At their core, they’re just rectangular containers with borders and padding. However, when utilized properly to group related information, they help users better digest, engage, and navigate through content.
Accordion panels Methods related to creating and updating vertically collapsing accordion panels.
Value boxes Prominently display a value and label in a box that can be expanded to show more information.
Tooltips Display additional information when focusing (or hovering over) a UI element.
Filling layouts Methods to create containers that are allowed to shrink or expand available space.
UI Inputs Additional or upgraded UI inputs.
Css Helper methods related to CSS.