ui.toolbar_input_button

ui.toolbar_input_button(
    id,
    label,
    *,
    icon=None,
    show_label=MISSING,
    tooltip=MISSING,
    disabled=False,
    border=False,
    **kwargs,
)

Create a toolbar button input.

A button designed to fit well in small places such as in a toolbar.

Parameters

id : str

The input ID.

label : TagChild

The input label. When an icon is provided, the label is hidden by default but is used by tooltip. When no icon is provided, the label is shown by default. Use show_label to control label visibility (see tooltip for details on how this affects the tooltip behavior).

icon : Optional[TagChild] = None

An icon. If provided without show_label = True, only the icon will be visible.

show_label : bool | MISSING_TYPE = MISSING

Whether to show the label text. Defaults to True when no icon is provided, and False when an icon is provided. If False, only the icon is shown (requires an icon). If True, the label text is shown (with icon if provided). Note that show_label can be dynamically updated using update_toolbar_input_button.

tooltip : bool | str | MISSING_TYPE = MISSING

Tooltip text to display when hovering over the input. Can be: * True (default when show_label = False) - shows a tooltip with the label text * False (default when show_label = True) - no tooltip * A character string - shows a tooltip with custom text Defaults to !show_label. When a tooltip is created, it will have an ID of "{id}_tooltip" which can be used to update the tooltip text via update_tooltip.

disabled : bool = False

If True, the button will not be clickable. Use update_toolbar_input_button to dynamically enable/disable the button.

border : bool = False

Whether to show a border around the button.

****kwargs** : TagAttrValue = {}

Additional attributes to pass to the button.

Returns

: Tag

A UI element

Notes

Updating toolbar buttons

Use update_toolbar_input_button to change the label, label visibility, icon, and disabled state of the button from the server.

Note that you cannot change the tooltip or border parameters after the button has been created, as these affect the button’s structure and ARIA attributes. Please use update_tooltip to update tooltip text.

When a tooltip is created for the select input, it will have an ID of "{id}_tooltip" which can be used to update the tooltip text dynamically via update_tooltip.

See Also

Examples

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

## file: app.py
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
    def output_example2():
        edit_clicks = input.edit()
        return f"Edit clicks: {edit_clicks}"

    @output
    @render.text
    def output_example3():
        edit_clicks = input.edit_with_label()
        return f"Edit clicks: {edit_clicks}"


app = App(app_ui, server)