express.ui.show_offcanvas

express.ui.show_offcanvas(offcanvas, *, session=None)

Show an offcanvas panel.

Programmatically displays an offcanvas panel in the user's session. offcanvas can be:

  • a string id of an offcanvas panel already in the UI, which is revealed; or
  • arbitrary tag content (e.g. an HTML string, a Tag, or a TagList), which is wrapped into a new anonymous offcanvas panel with default settings; or
  • an Offcanvas object created by offcanvas, which is rendered into the page (if needed) and shown.

Parameters

offcanvas : Union[str, TagChild, Offcanvas]

The panel’s id, tag content for a new panel, or an Offcanvas object.

session : Optional[Session] = None

The Session to show the panel in. If not provided, the session is inferred via get_current_session.

Returns

: str

The local (pre-namespace) ID of the displayed panel.

Note

If a panel with the same id is already present on the page, show_offcanvas() simply reveals it — the content is not re-rendered. To update an id’d panel’s content, update the reactive outputs it contains rather than calling show_offcanvas() again.

A plain string is always treated as an id lookup, and raises a ValueError if it looks like body text instead (it is empty or contains whitespace). To show new string content, wrap it in HTML or pass a offcanvas object.

See Also

Examples

#| standalone: true
#| components: [editor, viewer]
#| layout: vertical
#| viewerHeight: 400

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

ui.offcanvas(
    ui.p("This panel is declared in the UI."),
    title="Existing panel",
    id="existing_panel",
)
ui.input_action_button("show_existing_btn", "Show existing panel")
ui.input_action_button("show_server_btn", "Show server panel")
ui.input_action_button("show_markdown_btn", "Show markdown content")


@reactive.effect
@reactive.event(input.show_existing_btn)
def _():
    # Reveal a panel already declared in the UI, by its id.
    ui.show_offcanvas("existing_panel")


@reactive.effect
@reactive.event(input.show_server_btn)
def _():
    # Build and show a new, anonymous panel entirely from the server.
    ui.show_offcanvas(
        ui.offcanvas(
            ui.p("This panel was inserted dynamically by the server."),
            title="Server Panel",
            placement="left",
        )
    )


@reactive.effect
@reactive.event(input.show_markdown_btn)
def _():
    # Bare tag content (here, rendered Markdown) is wrapped into a new
    # anonymous panel with default settings.
    ui.show_offcanvas(ui.markdown("""
            ### Markdown content

            This panel's body was written in **Markdown** and wrapped
            into a new anonymous offcanvas by `show_offcanvas()`.
            """))