docs: Explicitly call out module usage in bookmark button

CHANGELOG.md

@@ -11,12 +11,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Improvements
 
-* `selectize`, `remove_button`, and `options` parameters of `ui.input_select()` have been deprecated; use `ui.input_selectize()` instead. (Thanks, @ErdaradunGaztea!) (#1947) 
+* `selectize`, `remove_button`, and `options` parameters of `ui.input_select()` have been deprecated; use `ui.input_selectize()` instead. (Thanks, @ErdaradunGaztea!) (#1947)
 
 * Improved the styling and readability of markdown tables rendered by `ui.Chat()` and `ui.MarkdownStream()`. (#1973)
 
 ### Bug fixes
 
+* Explicitly call out module usage in UI input bookmark button documentation. (#1983)
+
 
 ## [1.4.0] - 2025-04-08
 

shiny/bookmark/_button.py

@@ -28,6 +28,30 @@ def input_bookmark_button(
 
     A `bookmarkButton` is a [input_action_button()] with a default label that consists of a link icon and the text "Bookmark...". It is meant to be used for bookmarking state.
 
+    Default behavior
+    ----------------
+
+    By default, Shiny will listen for the default `id` being used and call
+    `session.bookmark()` on button click. However, this will not work if the bookmark
+    button is used within a module or more than one bookmark button is being utilized.
+
+    For both situations, a custom `id` value is required.
+
+    There are two recommendations to maintain the expected bookmark behavior:
+    * The supplied `id` value should be excluded from bookmarking with
+      `session.bookmark.exclude.append(ID)`.
+    * A reactive effect should be added that performs the bookmarking
+      (`session.bookmark()`) when the button is pressed.
+
+    ```python
+    session.bookmark.exclude.append("CUSTOM_ID")
+
+    @reactive.effect
+    @reactive.event(input.CUSTOM_ID)
+    async def _():
+        await session.bookmark()
+    ```
+
     Parameters
     ----------
     label
@@ -39,7 +63,7 @@ def input_bookmark_button(
     disabled
         Whether the button is disabled.
     id
-        An ID for the bookmark button. The only time it is necessary to set the ID unless you have more than one bookmark button in your application. If you specify an input ID, it should be excluded from bookmarking with `session.bookmark.exclude.append(ID)`, and you must create a reactive effect that performs the bookmarking (`session.bookmark()`) when the button is pressed.
+        An ID for the bookmark button.
     title
         A tooltip that is shown when the mouse cursor hovers over the button.
     kwargs