Shiny for Python

https://shiny.posit.co/py/
Admin
Shiny for Python is a framework for building reactive data and AI web applications and scalable...
Tokens:188,239
Snippets:1,877
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Bookmark Example Setup

Source: https://shiny.posit.co/py/api/core/bookmark.Bookmark.html

Initial imports for setting up bookmarking functionality in a Shiny application.

```python
from starlette.requests import Request
  

from shiny import App, Inputs, Outputs, Session, reactive, render, ui
from shiny.bookmark import BookmarkState
```

--------------------------------

### Update Toolbar Input Button Example

Source: https://shiny.posit.co/py/api/core/ui.update_toolbar_input_button.html

A complete example demonstrating the setup of toolbar buttons and the structure for updating them.

```python
from faicons import icon_svg
  

from shiny import App, Inputs, Outputs, Session, reactive, render, ui
  

app_ui = ui.page_fluid(
ui.h2("Update Toolbar Input Button Examples"),
ui.p(
"These examples demonstrate updating a toolbar button's label and icon on click."
),
ui.card(
ui.card_header(
"Update Label",
ui.toolbar(ui.toolbar_input_button("btn", label="Click me"), align="right"),
),
ui.card_body(
ui.output_text_verbatim("count"),
),
),
ui.card(
ui.card_header(
"Update Icon",
ui.toolbar(
ui.toolbar_input_button(
"btn_icon", label="Save", icon=icon_svg("floppy-disk")
),
align="right",
),
),
ui.card_body(
ui.output_text_verbatim("count_icon"),
),
),
)
  

  

def server(input: Inputs, output: Outputs, session: Session) -> None:
  

  

  

  
```

--------------------------------

### Full Application Example

Source: https://shiny.posit.co/py/api/express/express.ui.include_js.html

A complete example demonstrating how to reference a local JavaScript file using pathlib.

```python
from pathlib import Path
  

from shiny.express import ui
  

js_file = Path(__file__).parent / "js" / "app.js"
  

"If you see this page before 'OK'-ing the alert box, something went wrong"
  

ui.include_js(js_file)
```

--------------------------------

### Full bookmarking application example

Source: https://shiny.posit.co/py/api/core/bookmark.Bookmark.html

A complete example demonstrating UI restoration and bookmarking event handling.

```python
from starlette.requests import Request
  

from shiny import App, Inputs, Outputs, Session, reactive, render, ui
from shiny.bookmark import BookmarkState
  

  
# App UI **must** be a function to ensure that each user restores their own UI values.
def app_ui(request: Request):
return ui.page_fluid(
ui.markdown(
"Directions: "
"\n1. Change the radio buttons below"
"\n2. Refresh your browser."
"\n3. The radio buttons should be restored to their previous state."
"\n4. Check the console messages for bookmarking events."
),
ui.hr(),
ui.input_radio_buttons(
"letter",
"Choose a letter (Store in Bookmark 'input')",
choices=["A", "B", "C"],
),
ui.input_radio_buttons(
"letter_values",
"Choose a letter (Stored in Bookmark 'values' as lowercase)",
choices=["A", "B", "C"],
),
"Selection:",
ui.output_code("letters"),
)
  

  
def server(input: Inputs, output: Outputs, session: Session):
```

--------------------------------

### Initialize reactive polling example

Source: https://shiny.posit.co/py/api/core/reactive.poll.html

Setup imports and helper functions for a reactive polling implementation.

```python
import asyncio
import random
import sqlite3
from datetime import datetime
from typing import Any, Awaitable
  

import pandas as pd
  

from shiny import App, Inputs, Outputs, Session, reactive, render, ui
  

SYMBOLS = ["AAA", "BBB", "CCC", "DDD", "EEE", "FFF"]
  

  

def timestamp() -> str:
return datetime.now().strftime("%x %X")
  

  

def rand_price() -> float:
return round(random.random() * 250, 2)
```

--------------------------------

### Full Application Example

Source: https://shiny.posit.co/py/api/core/ui.include_css.html

A complete example showing how to include a CSS file from a path in a Shiny application.

```python
from pathlib import Path
  

from shiny import App, ui
  

css_file = Path(__file__).parent / "css" / "styles.css"
  

app_ui = ui.page_fluid(
"Almost before we knew it, we had left the ground!!!",
ui.include_css(css_file),
ui.div(
# Style individual elements with an attribute dictionary.
{"style": "font-weight: bold"},
ui.p("Bold text"),
),
)
  

app = App(app_ui, None)
```

--------------------------------

### Install Shiny

Source: https://shiny.posit.co/py/index.html

Install the Shiny package using pip.

```bash
pip install shiny
```

--------------------------------

### Initialize an editable data frame example

Source: https://shiny.posit.co/py/api/express/express.render.data_frame.html

Full setup for an editable data frame using reactive values.

```python
from shared import mtcars

from shiny import reactive
from shiny.express import render, ui

df = reactive.value(mtcars.iloc[:, range(4)])


with ui.layout_columns(col_widths=[4, 4, 4]):
with ui.card():
with ui.card_header():
ui.markdown("""
##### Editable data frame
* Edit the cells!
* Sort the columns!
""")

@render.data_frame
def df_original():
return render.DataGrid(
df(),
editable=True,
)
```

--------------------------------

### DataGrid Configuration Example

Source: https://shiny.posit.co/py/api/express/express.render.DataGrid.html

Example configuration for applying styles to DataGrid cells.

```json
"class": "posit-bg",
"style": {
"border": "transparent",
"color": "transparent",
},
},
{
"rows": [3],
```

--------------------------------

### Toast UI implementation example

Source: https://shiny.posit.co/py/api/core/ui.toast.html

Example showing how to integrate toast triggers within a card layout using action buttons.

```python
import time
"": "None",
"circle-check": "Check",
"circle-info": "Info",
"triangle-exclamation": "Warning",
"circle-xmark": "Error",
"star": "Star",
"heart": "Heart",
"bell": "Bell",
"user": "User",
"gear": "Settings",
"comments": "Chat",
"envelope": "Envelope",
"lightbulb": "Lightbulb",
"rocket": "Rocket",
"shield": "Shield",
"thumbs-up": "Thumbs Up",
"download": "Download",
"upload": "Upload",
"calendar": "Calendar",
"clock": "Clock",
"fire": "Fire",
"gift": "Gift",
"trophy": "Trophy",
"flag": "Flag",
"thumbtack": "Pin",
},
),
),
),
),
),
ui.card_footer(
ui.input_action_button(
"show_toast", "Show Toast", class_="btn-primary"
),
ui.input_action_button(
"hide_toast", "Hide Last Toast", class_="btn-secondary"
),
class_="hstack gap-2 justify-content-end",
),
),
ui.layout_column_wrap(
# Advanced Features
ui.card(
ui.card_header("Advanced Features"),
ui.card_body(
ui.input_action_button(
"show_persistent",
"Show Persistent Toast",
class_="mb-2 w-100",
),
ui.input_action_button(
"hide_persistent",
"Hide Persistent Toast",
class_="mb-2 w-100",
),
ui.input_action_button(
"show_long_duration",
"Long Duration (10s)",
class_="mb-2 w-100",
),
ui.input_action_button(
"show_no_close", "No Close Button", class_="mb-2 w-100"
),
ui.input_action_button(
"show_custom_header",
"Custom Header with Icon & Status",
class_="mb-2 w-100",
),
),
),
# Interactive Toasts
ui.card(
ui.card_header("Interactive Toasts"),
ui.card_body(
ui.input_action_button(
"show_action_buttons",
"Toast with Action Buttons",
class_="mb-2 w-100",
),
ui.input_action_button(
"show_multiple", "Show Multiple Toasts", class_="mb-2 w-100"
),
ui.input_action_button(
"show_all_positions", "Test All Positions", class_="mb-2 w-100"
),
ui.input_action_button(
"show_dynamic_content",
"Toast with Dynamic Content",
class_="mb-2 w-100",
),

```

--------------------------------

### Include CSS Example

Source: https://shiny.posit.co/py/api/express/express.ui.include_css.html

A complete example showing how to reference a CSS file and style elements using attributes.

```python
from pathlib import Path
  

from shiny.express import ui
  

css_file = Path(__file__).parent / "css" / "styles.css"
  

"Almost before we knew it, we had left the ground!!!"
  

ui.include_css(css_file)
  

# Style individual elements with an attribute dictionary.
ui.p("Bold text", {"style": "font-weight: bold"})
```

--------------------------------

### Download examples in Shiny Express

Source: https://shiny.posit.co/py/api/express/express.render.download.html

Examples demonstrating how to use @render.download_button for static file downloads and dynamic data generation.

```python
import asyncio
import io
import os
from datetime import date
  

import matplotlib.pyplot as plt
import numpy as np
  

from shiny.express import render, ui
  

ui.page_opts(title="Various download examples")
  

with ui.accordion(open=True):
with ui.accordion_panel("Simple case"):
ui.markdown("Downloads a pre-existing file, using its existing name on disk.")
  

# Uses @render.download_button (replaces the deprecated download renderer).
@render.download_button(label="Download CSV")
def download1():
"""
This is the simplest case. The implementation simply returns the name of a file.
Note that the function name (`download1`) determines which download_button()
corresponds to this function.
"""
  

path = os.path.join(os.path.dirname(__file__), "mtcars.csv")
return path
  

with ui.accordion_panel("Dynamic data generation"):
ui.markdown("Downloads a PNG that's generated on the fly.")
  

ui.input_text("title", "Plot title", "Random scatter plot")
ui.input_slider("num_points", "Number of data points", min=1, max=100, value=50)
  

@render.download_button(label="Download plot", filename="image.png")
def download2():
  

  

  

  

```

--------------------------------

### Install Logfire SDK

Source: https://shiny.posit.co/py/api/core/OpenTelemetry.html

Installs the Logfire package for code-based instrumentation.

```bash
pip install logfire
```

--------------------------------

### Full Application Example

Source: https://shiny.posit.co/py/api/core/ui.include_js.html

A complete example demonstrating how to reference a local JavaScript file and include it in a Shiny application UI.

```python
from pathlib import Path
  

from shiny import App, ui
  

js_file = Path(__file__).parent / "js" / "app.js"
  

app_ui = ui.page_fluid(
"If you see this page before 'OK'-ing the alert box, something went wrong",
ui.include_js(js_file),
)
  

  

app = App(app_ui, None)
```

--------------------------------

### Create a TagList example

Source: https://shiny.posit.co/py/api/core/ui.TagList.html

Demonstrates creating a TagList containing text and a div element.

```python
>>> from htmltools import TagList, div
>>> TagList("hello", div(id="foo", class_="bar"))
hello
<div id="foo" class="bar"></div>
```

--------------------------------

### Shiny download example application

Source: https://shiny.posit.co/py/api/core/render.download.html

A comprehensive example demonstrating various download scenarios including static files, dynamic plots, dynamic filenames, and error handling.

```python
import asyncio
import io
import os
from datetime import date
from typing import Any
  

import matplotlib.pyplot as plt
import numpy as np
  

from shiny import App, Inputs, Outputs, Session, render, ui
  

  
def make_example(id: str, label: str, title: str, desc: str, extra: Any = None):
return ui.column(
4,
ui.div(
{"class": "card mb-4"},
ui.div(title, class_="card-header"),
ui.div(
{"class": "card-body"},
ui.p(desc, class_="card-text text-muted"),
extra,
ui.download_button(id, label, class_="btn-primary"),
),
),
)
  

  
app_ui = ui.page_fluid(
ui.row(
make_example(
"download1",
label="Download CSV",
title="Simple case",
desc="Downloads a pre-existing file, using its existing name on disk.",
),
),
ui.row(
make_example(
"download2",
label="Download plot",
title="Dynamic data generation",
desc="Downloads a PNG that's generated on the fly.",
extra=[
ui.input_text("title", "Plot title", "Random scatter plot"),
ui.input_slider(
"num_points", "Number of data points", min=1, max=100, value=50
),
],
),
),
ui.row(
make_example(
"download3",
"Download",
"Dynamic filename",
"Demonstrates that filenames can be generated on the fly (and use Unicode characters!).",
),
),
ui.row(
make_example(
"download4",
"Download",
"Failed downloads",
"Throws an error in the download handler, download should not succeed.",
),
),
)
```

--------------------------------

### Configure Navbar Colors

Source: https://shiny.posit.co/py/api/core/ui.navbar_options.html

Examples of setting navbar background and theme using ui.navbar_options.

```python
ui.page_navbar(
  theme=ui.Theme(version=5, preset="flatly"),
  navbar_options=ui.navbar_options(class="bg-primary", theme="dark")
)
```

```python
ui.page_navbar(
  theme = ui.Theme(version=5, preset="flatly"),
  navbar_options = ui.navbar_options(class="bg-light", theme="light")
)
```

--------------------------------

### Install Shiny with OpenTelemetry

Source: https://shiny.posit.co/py/api/core/OpenTelemetry.html

Install the necessary dependencies for OpenTelemetry support in Shiny.

```bash
pip install "shiny[otel]"
```

--------------------------------

### Utility Classes Example

Source: https://shiny.posit.co/py/docs/ui-customize.html

Example of using Bootstrap utility classes for styling.

```python
from shiny.express import ui

with ui.card():
    ui.card_header("Card header", class_="bg-primary-subtle lead")
    "Card body"
```

--------------------------------

### Basic card usage

Source: https://shiny.posit.co/py/api/express/express.ui.card.html

Example of using the card context manager with a header, body content, and footer.

```python
from shiny.express import ui
  

with ui.card(full_screen=True):
ui.card_header("This is the header")
ui.p("This is the body.")
ui.p("This is still the body.")
ui.card_footer("This is the footer")
```

--------------------------------

### Example Usage of ui.input_action_link

Source: https://shiny.posit.co/py/api/core/ui.input_action_link.html

A complete application example demonstrating how to use ui.input_action_link to trigger a reactive plot update.

```python
import matplotlib.pyplot as plt
import numpy as np
  

from shiny import App, Inputs, Outputs, Session, reactive, render, ui
  

app_ui = ui.page_fluid(
ui.input_slider("n", "Number of observations", min=0, max=1000, value=500),
ui.input_action_link("go", "Go!"),
ui.output_plot("plot"),
)
  

  

def server(input: Inputs, output: Outputs, session: Session):
@render.plot(alt="A histogram")
# reactive.event() to invalidate the plot when the button is pressed but not when
# the slider is changed
@reactive.event(input.go, ignore_none=False)
def plot():
np.random.seed(19680801)
x = 100 + 15 * np.random.randn(input.n())
fig, ax = plt.subplots()
ax.hist(x, bins=30, density=True)
return fig
  

  

app = App(app_ui, server)
```

--------------------------------

### Running Shiny applications

Source: https://shiny.posit.co/py/api/core/run_app.html

Examples demonstrating how to launch Shiny applications from different file locations and module structures.

```python
from shiny import run_app

# Run ``app`` inside ``./app.py``
run_app()

# Run ``app`` inside ``./myapp.py`` (or ``./myapp/app.py``)
run_app("myapp")

# Run ``my_app`` inside ``./myapp.py`` (or ``./myapp/app.py``)
run_app("myapp:my_app")

# Run ``my_app`` inside ``../myapp.py`` (or ``../myapp/app.py``)
run_app("myapp:my_app", app_dir="..")
```

--------------------------------

### Run the Shiny App

Source: https://shiny.posit.co/py/api/core/App.html

Starts the application server.

```python
App.run(**kwargs)
```

--------------------------------

### App.run

Source: https://shiny.posit.co/py/api/core/App.html

Starts the Shiny application.

```APIDOC
## App.run(**kwargs)

### Description
Run the app.

### Parameters
- **kwargs** (object) - Optional - Keyword arguments passed to run_app.
```

--------------------------------

### run_app

Source: https://shiny.posit.co/py/api/core

Starts a Shiny application.

```APIDOC
## run_app

### Description
Starts a Shiny app. Press Ctrl+C (or Ctrl+Break on Windows) to stop the app.
```

--------------------------------

### Full Application Example

Source: https://shiny.posit.co/py/api/core/ui.update_nav_panel.html

A complete Shiny application demonstrating how to toggle visibility of tabs and menus using update_nav_panel.

```python
from shiny import App, Inputs, Outputs, Session, reactive, ui
  

app_ui = ui.page_sidebar(
ui.sidebar(
"Home",
ui.input_action_button("hideTab", "Hide 'Foo' tab"),
ui.input_action_button("showTab", "Show 'Foo' tab"),
ui.input_action_button("hideMenu", "Hide 'More' nav_menu"),
ui.input_action_button("showMenu", "Show 'More' nav_menu"),
),
ui.navset_tab(
ui.nav_panel("Foo", "This is the foo tab", value="Foo"),
ui.nav_panel("Bar", "This is the bar tab", value="Bar"),
ui.nav_menu(
"More",
ui.nav_panel("Table", "Table page"),
ui.nav_panel("About", "About page"),
"------",
"Even more!",
ui.nav_panel("Email", "Email page"),
value="More",
),
id="tabs",
),
title="Navbar page",
id="sidebar",
)
  

  

def server(input: Inputs, output: Outputs, session: Session):
@reactive.effect
@reactive.event(input.hideTab)
def _():
ui.update_nav_panel("tabs", target="Foo", method="hide")
  

@reactive.effect
```

--------------------------------

### Dashboard Layout Example

Source: https://shiny.posit.co/py/api/core/ui.layout_columns.html

A practical example showing how to use ui.layout_columns within a Shiny application to organize dashboard components.

```python
from model_plots import * # model plots and cards
  

from shiny import App, Inputs, Outputs, Session, render, ui
  

app_ui = ui.page_fluid(
ui.panel_title(ui.h2("Model Dashboard")),
ui.markdown("Using `ui.layout_columns()` for the layout."),
ui.layout_columns(
card_loss,
card_acc,
card_feat,
col_widths={"sm": (5, 7, 12)},
# row_heights=(2, 3),
# height="700px",
),
)
  

  

def server(input: Inputs, output: Outputs, session: Session):
@render.plot
def loss_over_time():
return plot_loss_over_time()
  

@render.plot
def accuracy_over_time():
return plot_accuracy_over_time()
  

@render.plot
def feature_importance():
return plot_feature_importance()
  

  

app = App(app_ui, server)
```

--------------------------------

### Multi-page Example

Source: https://shiny.posit.co/py/docs/overview.html

Illustrates a multi-page layout with a sidebar, a plot panel, and a table panel.

```python
import plotly.express as px
from shiny.express import input, render, ui
from shinywidgets import render_widget

ui.page_opts(title="Multi-page example", fillable=True)

with ui.sidebar():
    ui.input_select("var", "Select variable", choices=["total_bill", "tip"])

with ui.nav_panel("Plot"):
    @render_widget
    def hist():
        return px.histogram(px.data.tips(), input.var())

with ui.nav_panel("Table"):
    @render.data_frame
    def table():
        return px.data.tips()

```

--------------------------------

### Example of on_flush usage

Source: https://shiny.posit.co/py/api/core/Session.html

Demonstrates using on_flush to log and insert UI elements during a reactive flush.

```python
from datetime import datetime
  

from shiny import App, Inputs, Outputs, Session, render, ui
  

app_ui = ui.page_fluid(
ui.input_action_button("flush", "Trigger flush"),
ui.output_ui("n_clicks"),
ui.div(id="flush_time"),
)
  

  

def server(input: Inputs, output: Outputs, session: Session):
def log():
msg = "A reactive flush occurred at " + datetime.now().strftime("%H:%M:%S:%f")
print(msg)
ui.insert_ui(
ui.p(msg),
selector="#flush_time",
)
  

session.on_flush(log, once=False)
  

@render.ui
def n_clicks():
return "Number of clicks: " + str(input.flush())
  

  

app = App(app_ui, server)
```

--------------------------------

### Multi-column Example

Source: https://shiny.posit.co/py/docs/overview.html

Demonstrates a layout with multiple columns, each containing a plot and a data frame.

```python
import plotly.express as px
from shiny.express import input, render, ui
from shinywidgets import render_widget

ui.page_opts(title="Multi-column example")

ui.input_select("var", "Select variable", choices=["total_bill", "tip"])

with ui.layout_columns(height="300px"):
    @render_widget
    def hist():
        return px.histogram(px.data.tips(), input.var())

    @render.data_frame
    def table():
        return px.data.tips()

```

--------------------------------

### Full Navbar Application Example

Source: https://shiny.posit.co/py/api/core/ui.navbar_options.html

A complete Shiny application demonstrating the use of navbar_options within a navset_bar.

```python
from shiny import App, render, ui
  

app_ui = ui.page_fluid(
ui.navset_bar(
ui.nav_panel("A", "Panel A content"),
ui.nav_panel("B", "Panel B content"),
ui.nav_panel("C", "Panel C content"),
ui.nav_menu(
"Other links",
ui.nav_panel("D", "Panel D content"),
"----",
"Description:",
ui.nav_control(
ui.a("Shiny", href="https://shiny.posit.co", target="_blank")
),
),
id="selected_navset_bar",
title="Navset Bar",
navbar_options=ui.navbar_options(
bg="#B73A85",
theme="dark",
underline=False,
),
),
ui.h5("Selected:"),
ui.output_code("selected"),
)
  

  
def server(input, output, session):
@render.code
def selected():
return input.selected_navset_bar()
  

  
app = App(app_ui, server)
```

--------------------------------

### Create a navigation panel layout

Source: https://shiny.posit.co/py/api/core/ui.nav_panel.html

An example demonstrating nested navigation panels within a navset_bar and navset_card_underline.

```python
from shiny import App, Inputs, ui
  

app_ui = ui.page_fluid(
ui.navset_bar(
ui.nav_panel("Page 1", "Page 1 content"),
ui.nav_panel(
"Page 2",
ui.navset_card_underline(
ui.nav_panel("Tab 1", "Tab 1 content"),
ui.nav_panel("Tab 2", "Tab 2 content"),
ui.nav_panel("Tab 3", "Tab 3 content"),
),
),
title="Nav Panel Example",
),
)
  

  

def server(input: Inputs):
pass
  

  

app = App(app_ui, server)
```

--------------------------------

### Example of on_flushed usage

Source: https://shiny.posit.co/py/api/core/Session.html

Demonstrates using on_flushed to log and insert UI elements after a reactive flush.

```python
from datetime import datetime
  

from shiny import App, Inputs, Outputs, Session, render, ui
  

app_ui = ui.page_fluid(
ui.input_action_button("flush", "Trigger flush"),
ui.output_ui("n_clicks"),
ui.div(id="flush_time"),
)
  

  

def server(input: Inputs, output: Outputs, session: Session):
def log():
msg = "A reactive flush occurred at " + datetime.now().strftime("%H:%M:%S:%f")
print(msg)
ui.insert_ui(
ui.p(msg),
selector="#flush_time",
)
  

session.on_flushed(log, once=False)
  

@render.ui
def n_clicks():
return "Number of clicks: " + str(input.flush())
  

  

app = App(app_ui, server)
```

--------------------------------

### Initialize data frame application

Source: https://shiny.posit.co/py/api/express/express.render.data_frame.html

Setup imports and reactive data for a data frame application.

```python
from __future__ import annotations

from pathlib import Path

import pandas as pd

from shiny import reactive
from shiny.express import render, ui

here = Path(__file__).parent
mtcars_df = reactive.value(pd.read_csv(here / "mtcars.csv").iloc[:, range(4)])
```

--------------------------------

### Create a responsive column layout

Source: https://shiny.posit.co/py/api/core/ui.column.html

Example demonstrating the use of ui.column within a ui.row to organize UI elements.

```python
import matplotlib.pyplot as plt
import numpy as np
  

from shiny import App, Inputs, Outputs, Session, render, ui
  

app_ui = ui.page_fluid(
ui.row(
ui.column(4, ui.input_slider("n", "N", min=1, max=100, value=20)),
ui.column(8, ui.output_plot("plot")),
)
)
  

  

def server(input: Inputs, output: Outputs, session: Session):
@render.plot(alt="A histogram")
def plot() -> object:
np.random.seed(19680801)
x = 100 + 15 * np.random.randn(437)
  

fig, ax = plt.subplots()
ax.hist(x, input.n(), density=True)
return fig
  

  

app = App(app_ui, server)
```

--------------------------------

### Configure global bookmark storage

Source: https://shiny.posit.co/py/api/core/bookmark_integration.html

Example showing the implementation of custom save and restore directory functions and their registration as global defaults.

```python
from pathlib import Path
from shiny.bookmark import set_global_save_dir_fn, set_global_restore_dir_fn

bookmark_dir = Path(__file__).parent / "bookmarks"

def save_bookmark_dir(id: str) -> Path:
    save_dir = bookmark_dir / id
    save_dir.mkdir(parents=True, exist_ok=True)
    return save_dir

def restore_bookmark_dir(id: str) -> Path:
    return bookmark_dir / id

# Set global defaults for bookmark saving and restoring.
set_global_restore_dir_fn(restore_bookmark_dir)
set_global_save_dir_fn(save_bookmark_dir)

app = App(app_ui, server, bookmark_store="server")
```

--------------------------------

### Distributing styles with HTMLDependency

Source: https://shiny.posit.co/py/docs/ui-customize.html

An example of creating a function that returns an HTMLDependency object for distributing custom styles and scripts, making them accessible after installing a Python package.

```python
from htmltools import HTMLDependency

def acme_theme():
    return HTMLDependency(
        name="acme_theme",
        version="0.01",
        source={"package": "acme_theme", "subdir": "acme-theme"},
        stylesheet=[{"href": "acme-theme.css"}],
        script=[{"src": "acme-theme.js"}],
        # If you want other files in the acme-theme dir to be served
        all_files=True
    )
```

--------------------------------

### Initialize ui.Theme

Source: https://shiny.posit.co/py/api/core/ui.Theme.html

Constructor signature for creating a new theme instance.

```python
ui.Theme(preset=None, name=None, include_paths=None)
```

--------------------------------

### Create a Shiny Project

Source: https://shiny.posit.co/py/index.html

Initialize a new Shiny project using the dashboard-tips template.

```bash
shiny create --template dashboard-tips
```

--------------------------------

### Custom Renderer Implementation Example

Source: https://shiny.posit.co/py/api/core/Renderer.html

Demonstrates how to use custom renderers with and without parentheses in a Shiny application.

```python
from renderers import render_capitalize, render_upper
  

from shiny import App, Inputs, Outputs, Session, ui
  

app_ui = ui.page_fluid(
ui.h1("Capitalization renderer"),
ui.input_text("caption", "Caption:", "Data summary"),
"@render_upper: ",
ui.output_text_verbatim("upper", placeholder=True),
"@render_upper(): ",
ui.output_text_verbatim("upper_with_paren", placeholder=True),
"@render_capitalize: ",
ui.output_text_verbatim("cap_upper", placeholder=True),
"@render_capitalize(to='lower'): ",
ui.output_text_verbatim("cap_lower", placeholder=True),
)
  

  

def server(input: Inputs, output: Outputs, session: Session):
# Hovering over `@render_upper` will display the class documentation
@render_upper
def upper():
return input.caption()
  

# Hovering over `@render_upper` will display the class documentation as there is no
# `__init__()` documentation
@render_upper()
def upper_with_paren():
return input.caption()
  

# Hovering over `@render_capitalize` will display the class documentation
@render_capitalize
def cap_upper():
return input.caption()
  

# Hovering over `@render_capitalize` will display the `__init__()` documentation
@render_capitalize(to_case="lower")
def cap_lower():
return input.caption()
  

  

app = App(app_ui, server)
```

--------------------------------

### Usage example of render_capitalize

Source: https://shiny.posit.co/py/api/core/render.transformer.output_transformer.html

Example showing the decorator applied to a function.

```python
@render_capitalize
def value():
return input.caption()
```

--------------------------------

### Toolbar Input Select Examples

Source: https://shiny.posit.co/py/api/core/ui.toolbar_input_select.html

Demonstrates various configurations for toolbar select inputs, including basic usage, icons with tooltips, and grouped choices.

```python
from faicons import icon_svg
  

from shiny import App, Inputs, Outputs, Session, render, ui
  

app_ui = ui.page_fluid(
ui.h2("Toolbar Input Select Examples"),
ui.p(
"Examples showing different ways to configure toolbar_input_select: basic, with icon and tooltip, and grouped choices."
),
ui.card(
ui.card_header(
"Basic Select",
ui.toolbar(
ui.toolbar_input_select(
id="select",
label="Choose option",
choices=["Option 1", "Option 2", "Option 3"],
selected="Option 2",
),
align="right",
),
),
ui.card_body(
ui.output_text("output_example1"),
),
),
ui.card(
ui.card_header(
"With Icon and Tooltip",
ui.toolbar(
ui.toolbar_input_select(
id="filter",
label="Filter",
choices=["All", "Active", "Archived"],
icon=icon_svg("filter"),
tooltip="Filter the data",
),
align="right",
),
),
ui.card_body(
ui.output_text("output_example2"),
),
),
ui.card(
ui.card_header(
"Grouped Choices",
ui.toolbar(
ui.toolbar_input_select(
id="grouped",
label="Select item",
choices={
"Group A": {"a1": "Choice A1", "a2": "Choice A2"},
"Group B": {"b1": "Choice B1", "b2": "Choice B2"},
},
),
align="right",
),
),
ui.card_body(
ui.output_text("output_example3"),
),
),
)
```

--------------------------------

### Initialize help_text function

Source: https://shiny.posit.co/py/api/express/express.ui.help_text.html

The basic signature for creating a help text element.

```python
express.ui.help_text(*args, **kwargs)
```

--------------------------------

### Tag Example

Source: https://shiny.posit.co/py/api/core/TagTypes.html

Example of creating and displaying a div tag.

```python
>>> from htmltools import div
>>> x = div("hello", id="foo", class_="bar")
>>> x
<div id="foo" class="bar">hello</div>
>>> x.show()
```

--------------------------------

### Accordion Panel Usage Example

Source: https://shiny.posit.co/py/api/express/express.ui.accordion_panel.html

Demonstrates creating multiple accordion panels within an accordion container using a loop.

```python
from shiny.express import input, render, ui

with ui.accordion(id="acc"):
    for letter in "ABCDE":
        with ui.accordion_panel(f"Section {letter}"):
            f"Some narrative for section {letter}"

@render.code
def acc_val():
    return "input.acc(): " + str(input.acc())
```

--------------------------------

### Inline Styles Example

Source: https://shiny.posit.co/py/docs/ui-customize.html

Example of applying inline styles directly to a UI component.

```python
from shiny.express import ui

with ui.card():
    ui.card_header("Card header", style="color:white; background:#2A2A2A !important;")
    "Card body"
```

--------------------------------

### Shinyswatch Example

Source: https://shiny.posit.co/py/docs/ui-customize.html

Example of using the shinyswatch package to apply a theme to a Shiny app.

```python
from shinyswatch import theme
from shiny.express import render, ui


ui.page_opts(title="Hello shinyswatch theme", theme=theme.darkly)

with ui.sidebar():
    "Sidebar content"

"Main content"
```

--------------------------------

### Create a Basic Shiny Application

Source: https://shiny.posit.co/py/api/core/App.html

A minimal example showing the definition of UI and server components passed to the App constructor.

```python
from shiny import  App, Inputs, Outputs, Session, ui

app_ui = ui.page_fluid("Hello Shiny!")

def server(input: Inputs, output: Outputs, session: Session):
    pass

app = App(app_ui, server)
```

--------------------------------

### Remove UI Example

Source: https://shiny.posit.co/py/api/core/ui.remove_ui.html

An example demonstrating how to remove a text input element when an action button is clicked.

```python
from shiny import App, Inputs, Outputs, Session, reactive, ui
  

app_ui = ui.page_fluid(
ui.input_action_button("rmv", "Remove UI"),
ui.input_text("txt", "Click button above to remove me"),
)
  

  

def server(input: Inputs, output: Outputs, session: Session):
@reactive.effect
@reactive.event(input.rmv)
def _():
ui.remove_ui(selector="div:has(> #txt)")
  

  

app = App(app_ui, server)
```

--------------------------------

### Initialize Theme Object

Source: https://shiny.posit.co/py/api/express/express.ui.Theme.html

Constructor signature for creating a new Theme instance.

```python
express.ui.Theme(preset=None, name=None, include_paths=None)
```

--------------------------------

### Remove accordion panel example

Source: https://shiny.posit.co/py/api/core/ui.remove_accordion_panel.html

Example demonstrating the removal of an accordion panel using a button trigger.

```python
import random
  

from shiny import App, Inputs, Outputs, Session, reactive, ui
  

def make_panel(letter: str) -> ui.AccordionPanel:
return ui.accordion_panel(
f"Section {letter}", f"Some narrative for section {letter}"
)
  

items = [make_panel(letter) for letter in "ABCDE"]
  
choices = ["A", "B", "C", "D", "E"]
random.shuffle(choices)
  
app_ui = ui.page_fluid(
ui.input_action_button(
"remove_panel",
f"Remove Section {choices[-1]}",
class_="mt-3 mb-3",
),
" (Sections randomly picked at server start)",
ui.accordion(*items, id="acc", multiple=True),
)
  

def server(input: Inputs, output: Outputs, session: Session):
# Copy the list for user
user_choices = [choice for choice in choices]
  
@reactive.effect
@reactive.event(input.remove_panel)
def _():
if len(user_choices) == 0:
ui.notification_show("No more panels to remove!")
```

--------------------------------

### Custom CSS File Example

Source: https://shiny.posit.co/py/docs/ui-customize.html

Example of importing an external CSS file using ui.include_css().

```python
from pathlib import Path
from shiny.express import ui

ui.include_css(
    Path(__file__).parent / "my-styles.css"
)

with ui.card():
    ui.card_header("Card header")
    "Card body"
```

--------------------------------

### Theme Constructor

Source: https://shiny.posit.co/py/api/express/express.ui.Theme.html

Initializes a new Theme instance with optional preset, name, and include paths.

```APIDOC
## Theme(preset=None, name=None, include_paths=None)

### Description
Creates a theme configuration for a Shiny application. Users can specify a base preset, a custom name, and additional paths for Sass file resolution.

### Parameters
- **preset** (str | None) - Optional - The name of the preset to use (e.g., 'shiny', 'bootstrap', or Bootswatch themes). Defaults to 'shiny'.
- **name** (Optional[str]) - Optional - A custom name for the theme. Defaults to the preset name if not provided.
- **include_paths** (Optional[str | pathlib.Path | list[str | pathlib.Path]]) - Optional - Additional directories to search for Sass files used in @import statements.

### Raises
- **ValueError** - Raised if the provided `preset` is not a valid theme preset.
```

--------------------------------

### Snapshot Preprocessing Example

Source: https://shiny.posit.co/py/api/core/Renderer.html

Example of using snapshot_preprocess to scrub non-deterministic values like timestamps from test snapshots.

```python
from datetime import datetime
  

from shiny import App, Inputs, Outputs, Session, render, ui
  

app_ui = ui.page_fluid(
ui.input_text("name", "Name", value="Shiny"),
ui.output_text_verbatim("greeting"),
)
  

  

def server(input: Inputs, output: Outputs, session: Session):
@render.text
def greeting() -> str:
return f"Hello, {input.name()}! It is {datetime.now().isoformat()}."
```

--------------------------------

### CSS Variables Example

Source: https://shiny.posit.co/py/docs/ui-customize.html

Example of customizing app styles by setting Bootstrap's CSS variables.

```python
from shiny.express import ui

ui.tags.style(":root { --bs-primary-rgb: 113,46,246; }")

with ui.card():
    ui.card_header("Card header", class_="bg-primary lead"),
    "Card body"
```

--------------------------------

### Initialize ui.TagList

Source: https://shiny.posit.co/py/api/core/ui.TagList.html

Constructor signature for creating a new TagList instance.

```python
ui.TagList(*args)
```

--------------------------------

### Custom CSS String Example

Source: https://shiny.posit.co/py/docs/ui-customize.html

Example of adding a CSS string directly to the UI using ui.tags.style().

```python
from shiny.express import ui

ui.tags.style(
    ".card-header { color:white; background:#2A2A2A !important; }"
)

with ui.card():
    ui.card_header("Card header")
    "Card body"
```

--------------------------------

### Code Editor Usage Example

Source: https://shiny.posit.co/py/api/express/express.ui.input_code_editor.html

A complete example demonstrating how to use the code editor within a Shiny Express application.

```python
#| '!! shinylive warning !!': |
#|   shinylive does not work in self-contained HTML documents.
#|   Please set `embed-resources: false` in your metadata.
#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 400

## file: app.py
from shiny.express import input, render, ui

ui.page_opts(fillable=True)

with ui.layout_columns(col_widths=[6, 6]):
    with ui.card():
        ui.card_header("Python Code Editor")
        ui.input_code_editor(
            "code",
            label="Enter Python code:",
            value="def greet(name):\n    return f'Hello, {name}!'\n\nprint(greet('World'))",
            language="python",
            height="200px",
        )

    with ui.card():
        ui.card_header("Editor Value")

        @render.text
        def value():
            return input.code()
```

--------------------------------

### Implement ui.input_selectize in an application

Source: https://shiny.posit.co/py/api/core/ui.input_selectize.html

A complete example demonstrating how to use ui.input_selectize with grouped choices, multiple selection, and custom selectize.js options.

```python
from html import escape # noqa: F401
  

from shiny import App, Inputs, Outputs, Session, render, ui
  

states = {
"East Coast": {"NY": "New York", "NJ": "New Jersey", "CT": "Connecticut"},
"West Coast": {"WA": "Washington", "OR": "Oregon", "CA": "California"},
"Midwest": {"MN": "Minnesota", "WI": "Wisconsin", "IA": "Iowa"},
}
  

app_ui = ui.page_fluid(
ui.input_selectize(
"state",
"Choose a state:",
states,
multiple=True,
),
ui.output_text("value"),
ui.input_selectize(
"state2",
"Selectize Options",
states,
multiple=True,
options=(
{
"placeholder": "Enter text",
"render": ui.js_eval(
'{option: function(item, escape) {return "<div><strong>Select " + escape(item.label) + "</strong></div>";}}'
),
"create": True,
}
),
),
ui.input_selectize(
"state3",
"Selectize plugins",
  

  

  


```

--------------------------------

### Initialize Bookmark

Source: https://shiny.posit.co/py/api/core/bookmark.Bookmark.html

Basic instantiation of the Bookmark class.

```python
bookmark.Bookmark()
```

--------------------------------

### Implement responsive column layouts

Source: https://shiny.posit.co/py/api/core/ui.layout_column_wrap.html

Demonstrates using ui.layout_column_wrap to create fixed-column grids and responsive grids based on viewport width.

```python
from shiny import App, ui
  

y = ui.card("A simple card")
  

app_ui = ui.page_fluid(
# Always has 2 columns (on non-mobile)
ui.layout_column_wrap(y, y, y, width=1 / 2),
ui.hr(),
# Has three columns when viewport is wider than 750px
ui.layout_column_wrap(y, y, y, width="250px"),
)
  

  

app = App(app_ui, server=None)
```

--------------------------------

### Basic DataGrid example

Source: https://shiny.posit.co/py/api/core/render.DataGrid.html

This example demonstrates how to use render.DataGrid to display a pandas DataFrame in a Shiny app. It includes options for selection mode, filters, and editability.

```python
import pandas as pd
import seaborn as sns
  
from shiny import App, Inputs, Outputs, Session, reactive, render, ui
  
app_ui = ui.page_fluid(
ui.head_content(
ui.tags.meta(name="viewport", content="width=device-width, initial-scale=1")
),
ui.input_select(
"selection_mode",
"Selection mode",
{
"none": "(None)",
"row": "Single row",
"rows": "Multiple rows",
},
selected="rows",
),
ui.input_switch("filters", "Filters", True),
ui.input_switch("editable", "Editable", True),
ui.layout_column_wrap(
ui.card(
ui.card_header("Data Frame as ", ui.tags.code("render.DataGrid")),
ui.output_data_frame("grid"),
),
ui.card(
ui.card_header("Data Frame as ", ui.tags.code("render.DataTable")),
ui.output_data_frame("table"),
),
width=1 / 2,
),
class_="p-3",
)
  
  
def server(input: Inputs, output: Outputs, session: Session):
    df: reactive.value[pd.DataFrame] = reactive.value(
      sns.load_dataset("anagrams").iloc[:, 1:]
    )
  
    def update_data_with_patch(patch):
      df_copy = df().copy()
      fn = str if patch["column_index"] == 0 else int
      df_copy.iat[patch["row_index"], patch["column_index"]] = fn(patch["value"])
      df.set(df_copy)
  
    height = 350
    width = "fit-content"
  
    @render.data_frame
    def grid():
      return render.DataGrid(
        df(),
        width=width,
        height=height,
        filters=input.filters(),
        editable=input.editable(),
        selection_mode=input.selection_mode(),
      )
  
    @grid.set_patch_fn
    def _(*, patch: render.CellPatch):
      update_data_with_patch(patch)
      return patch["value"]
  
  
  
  
app = App(app_ui, server)
```

--------------------------------

### Initialize ui.Progress

Source: https://shiny.posit.co/py/api/core/ui.Progress.html

Basic constructor signature for creating a progress bar instance.

```python
ui.Progress(min=0, max=1, session=None)
```

--------------------------------

### Example app using the custom Tabulator output

Source: https://shiny.posit.co/py/docs/custom-component-one-off.html

An example Shiny Express app that utilizes the custom `render_tabulator` decorator to display a subset of the `mtcars` dataset in a Tabulator table.

```python
from pathlib import Path
import pandas as pd
from shiny.express import input, ui

# Code for the custom output
...

# App code
ui.input_slider("n", "Number of rows to show", 1, 20, 10)

@render_tabulator
def tabulatorTable():
    return pd.read_csv(Path(__file__).parent / "mtcars.csv").head(input.n())
```

--------------------------------

### ui.input_date_range usage examples

Source: https://shiny.posit.co/py/api/core/ui.input_date_range.html

Demonstrates various configurations for date range inputs, including setting default dates, custom formats, and localization.

```python
from datetime import date
  

from shiny import App, Inputs, Outputs, Session, ui
  

app_ui = ui.page_fluid(
# Default start and end is the current date in the client's time zone
ui.input_date_range("daterange1", "Date range:"),
# Set start and end dates
ui.input_date_range(
"daterange2", "Set start and end date:", start="2001-01-01", end="2010-12-31"
),
# Start and end are always specified in yyyy-mm-dd, even if the display
# format is different
ui.input_date_range(
"daterange3",
"Min, max, start, and end dates are set with custom format and separator:",
start="2001-01-01",
end="2010-12-31",
min="2001-01-01",
max="2012-12-21",
format="mm/dd/yy",
separator=" - ",
),
# Pass in Date objects
ui.input_date_range(
"daterange4",
"Default start and end use date objects:",
start=date(2001, 1, 1),
end=date(2010, 12, 31),
),
# Use different language and different first day of week
ui.input_date_range(
"daterange5",
"Language is German and we starts on Monday:",
language="de",
weekstart=1,
  

  

  

  
)
```

--------------------------------

### Initialize FileInfo

Source: https://shiny.posit.co/py/api/core/MiscTypes.html

Instantiates the FileInfo class.

```python
types.FileInfo()
```

--------------------------------

### Creating a workout plan app template

Source: https://shiny.posit.co/py/docs/genai-inspiration.html

Command to initialize a Shiny application template for a workout plan generator.

```bash
shiny create --template workout-plan \
    --github posit-dev/py-shiny-templates/gen-ai
```

--------------------------------

### run.run_shiny_app

Source: https://shiny.posit.co/py/api/testing

Starts a Shiny application in a background subprocess.

```APIDOC
## run.run_shiny_app

### Description
Run a Shiny app in a subprocess.

### Signature
`run.run_shiny_app(app_path: str)`
```

--------------------------------

### Create a theme from brand configuration

Source: https://shiny.posit.co/py/api/core/ui.Theme.html

Initializes a theme object using a brand definition.

```python
ui.Theme.from_brand(brand)
```

--------------------------------

### Toolbar Input Button Examples

Source: https://shiny.posit.co/py/api/core/ui.toolbar_input_button.html

Demonstrates various configurations of toolbar_input_button including label-only, icon-only, and label with icon and custom tooltip.

```python
from faicons import icon_svg
  

from shiny import App, Inputs, Outputs, Session, render, ui
  

app_ui = ui.page_fluid(
ui.h2("Toolbar Input Button Examples"),
ui.p(
"Examples showing different ways to configure toolbar_input_button: label-only, icon-only, and label with icon and custom tooltip."
),
ui.card(
ui.card_header(
"Label-only Button",
ui.toolbar(
ui.toolbar_input_button(id="save", label="Save"),
align="right",
),
),
ui.card_body(
ui.output_text("output_example1"),
),
),
ui.card(
ui.card_header(
"Icon-only Button",
ui.toolbar(
ui.toolbar_input_button(
id="edit", label="Edit", icon=icon_svg("pencil")
),
align="right",
),
),
ui.card_body(
ui.output_text("output_example2"),
),
),
ui.card(
ui.card_header(
"Label and Icon Button",
ui.toolbar(
ui.toolbar_input_button(
id="edit_with_label",
label="Edit",
show_label=True,
icon=icon_svg("pencil"),
tooltip="Edit Document",
),
align="right",
),
),
ui.card_body(
ui.output_text("output_example3"),
),
),
)
  

  

def server(input: Inputs, output: Outputs, session: Session) -> None:
@output
@render.text
def output_example1():
save_clicks = input.save()
return f"Save clicks: {save_clicks}"
  

@output
@render.text
```

--------------------------------

### Get chat greeting

Source: https://shiny.posit.co/py/api/core/ui.Chat.html

Retrieves the current greeting content if it exists.

```python
ui.Chat.get_greeting()
```

--------------------------------

### Bootstrap Navbar Markup

Source: https://shiny.posit.co/py/api/core/ui.navbar_options.html

Example HTML markup for a Bootstrap 5 navbar.

```html
<nav class="navbar navbar-expand-lg bg-primary" data-bs-theme="dark">
  <!-- all of the navbar html -->
</nav>
```

--------------------------------

### Create a dashboard template

Source: https://shiny.posit.co/py/docs/overview.html

Use the `shiny create` CLI command with the `--template dashboard` option to quickly generate a dashboard starter template.

```bash
shiny create --template dashboard
```

--------------------------------

### Run Jaeger container

Source: https://shiny.posit.co/py/api/core/OpenTelemetry.html

Starts a local Jaeger instance for trace collection.

```bash
docker run -d --name jaeger \
    -p 16686:16686 \
    -p 4317:4317 \
    jaegertracing/all-in-one:latest
```
Tokens:
Raw