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),
  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)

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.

ui.HTML

Mark a string as raw HTML.

ui.TagList(*args)

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

ui.tags

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.

render.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.

render.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.

render.text()

Reactively render text.

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

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

render.ui()

Reactively render HTML content.

Reactive programming#

Reactive programming facilities for Python.

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.isolate()

Create a non-reactive scope within a reactive scope.

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

Scheduled Invalidation

reactive.flush()

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)

Deprecated.

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.

ui.modal_remove([session])

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.

types.SilentException

Throw a silent exception.

types.SilentCancelOutputException

Throw a silent exception and don't clear output

types.SafeException

Throw a safe exception.

Modules#

Control application complexity by namespacing UI and server code.

module.ui(fn)

rtype

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

module.server(fn)

rtype

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.

session.get_current_session()

Get the current user session.

session.require_active_session(session)

Raise an exception if no Shiny session is currently active.

session.session_context(session)

Context manager for current session.

reactive.get_current_context()

Get the current reactive context.

input_handler.input_handlers

Manage Shiny input handlers.