Bookmarking
DevelopmentbookmarkingBookmarking is an Agent Skill for development published in the posit-dev/py-shiny repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when a Shiny for Python (py-shiny) app needs to save and restore its state - shareable URLs that reproduce the current inputs, restoring state after a page refresh, persisting session state to the server, excluding inputs from saved state, or when tempted to hand-roll query-string parsing or a custom persistence layer to remember input values.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/posit-dev/py-shiny/blob/HEAD/shiny/.agents/skills/bookmarking/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/bookmarking, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Bookmarking Shiny for Python apps
Overview
Bookmarking snapshots an app's input values (plus optional custom values) and
restores them later from a URL. Use it instead of manually encoding state into
query strings or building a custom persistence layer.
Store values
bookmark_store (on App(...) or app_opts(...)) accepts three values:
| Value | Where state lives | Trade-offs |
|---|---|---|
"url" | Entirely in the URL query string | Shareable anywhere with zero server setup. Keep the serialized state under ~65k characters; file inputs cannot be serialized. |
"server" | On disk; the URL carries only a state id | Handles large state and file inputs (files are copied into the state directory). URLs only restore on a deployment that still has that directory — the hosting environment must persist it (see "Server-side storage location"). |
"disable" | Nowhere (the default) | Bookmarking is off: session.bookmark() warns and does nothing. |
Prefer "url" whenever the state fits — it needs no storage management.
Enable bookmarking
Express mode — call app_opts at the top of the app file:
from shiny.express import app_opts, session, ui
app_opts(bookmark_store="url")
ui.input_radio_buttons("letter", "Choose a letter", choices=["A", "B", "C"])
ui.input_bookmark_button()
@session.bookmark.on_bookmarked
async def _(url: str):
await session.bookmark.update_query_string(url)
Core mode — the UI must be a function taking a starlette.Request
(a static UI object cannot receive restored values), and App needs
bookmark_store=:
from starlette.requests import Request
from shiny import App, Inputs, Outputs, Session, ui
def app_ui(request: Request):
return ui.page_fluid(
ui.input_radio_buttons("letter", "Choose a letter", choices=["A", "B", "C"]),
ui.input_bookmark_button(),
)
def server(input: Inputs, output: Outputs, session: Session):
@session.bookmark.on_bookmarked
async def _(url: str):
await session.bookmark.update_query_string(url)
app = App(app_ui, server, bookmark_store="url")
With this in place, all inputs are saved on bookmark and restored on page load automatically — no per-input code needed.
Trigger a bookmark
- UI button:
ui.input_bookmark_button()— clicking it callssession.bookmark()for you. - Programmatic (e.g. bookmark on every change):
@reactive.effect
@reactive.event(input.letter, ignore_init=True)
async def _():
await session.bookmark()
After the state is saved, on_bookmarked callbacks receive the bookmark URL.
If none are registered, a modal dialog shows the URL; registering the
update_query_string(url) callback (as above) writes it to the browser's
address bar instead.
Save and restore custom (non-input) values
Reactive values, computed state, etc. go in state.values — do NOT create
hidden inputs to smuggle them into the bookmark:
from shiny.bookmark import BookmarkState, RestoreState
@session.bookmark.on_bookmark
def _(state: BookmarkState):
state.values["page"] = current_page()
@session.bookmark.on_restore
def _(state: RestoreState):
if "page" in state.values:
ui.update_radio_buttons("page", selected=state.values["page"])
Unlike inputs, state.values are never applied to the UI automatically — apply
them yourself in on_restore (runs before reactive expressions) or, for slow
late-rendering components, on_restored (runs after). state.input is also
readable in these callbacks, but input restoration has already happened via the
UI.
Exclude inputs
session.bookmark.exclude.append("transient_input")
Passwords are excluded automatically; file inputs are unserializable under
"url" storage. For custom exclusion logic, register a serializer:
session.input.set_serializer(id, fn) where fn returns a JSON-serializable
value or shiny.bookmark.Unserializable().
Server-side storage location
For bookmark_store="server" in hosted environments, control where state is
written (set these before creating the App):
from pathlib import Path
from shiny.bookmark import set_global_restore_dir_fn, set_global_save_dir_fn
bookmark_dir = Path(__file__).parent / "bookmarks"
def save_dir(id: str) -> Path:
d = bookmark_dir / id
d.mkdir(parents=True, exist_ok=True)
return d
set_global_save_dir_fn(save_dir)
set_global_restore_dir_fn(lambda id: bookmark_dir / id)
Quick reference
| Need | API |
|---|---|
| Enable (Express / Core) | app_opts(bookmark_store="url") / App(..., bookmark_store="url") |
| Bookmark now | await session.bookmark() |
| Put bookmark URL in address bar | session.bookmark.update_query_string(url) inside on_bookmarked |
| Get URL without side-band UI | await session.bookmark.get_bookmark_url() |
| Lifecycle hooks | session.bookmark.on_bookmark / on_bookmarked / on_restore / on_restored |
| Skip an input | session.bookmark.exclude.append(id) |
| Custom input component restores itself | shiny.bookmark.restore_input(resolved_id, default) when building its HTML |
Common mistakes
- Core-mode UI defined as a plain object → nothing restores. The UI must be a
function accepting a
Request. bookmark_storeleft unset (default"disable") →session.bookmark()warns and does nothing.- Expecting
state.valuesto restore into the UI automatically → they are server-only; callui.update_*()inon_restore. ui.input_bookmark_button()inside a module (or two buttons in one app) → the default id only auto-bookmarks at the top level. Give each button a uniqueid=, exclude that id, and wire your own@reactive.event(input.<id>)effect that callsawait session.bookmark().- Mutating
state.inputinon_bookmarkto drop values → ignored on save; usesession.bookmark.excludeinstead. - Module inputs missing from
state.valueschecks → names are prefixed with the module namespace, like inputs and outputs.