feat: run_button

docs/api/inputs/button.md

@@ -1,5 +1,12 @@
 # Button
 
+```{admonition} Looking for a submit/run button?
+:class: tip
+
+If you're looking for a button to trigger computation on click, consider
+using [`mo.ui.run_button`](/api/inputs/run_button.md).
+```
+
 ```{eval-rst}
 .. marimo-embed::
     @app.cell

docs/api/inputs/run_button.md

@@ -0,0 +1,31 @@
+# Run Button
+
+```{eval-rst}
+.. marimo-embed::
+    @app.cell
+    def __():
+        b = mo.ui.run_button()
+        b
+        return
+
+    @app.cell
+    def __():
+        s = mo.ui.slider(1, 10)
+        s
+        return
+
+
+    @app.cell
+    def __():
+        mo.stop(b.value, "Click `run` to submit the slider's value")
+
+        s.value
+        return
+```
+
+```{eval-rst}
+.. autoclass:: marimo.ui.run_button
+  :members:
+
+  .. autoclasstoc:: marimo._plugins.ui._impl.run_button.run_button
+```

docs/recipes.md

@@ -388,6 +388,36 @@ form.value
 
 ## Working with buttons
 
+### Create a button that triggers computation when clicked
+
+**Use cases.** To trigger a computation on button click and only on button
+click, use [`mo.ui.run_button()`](/api/inputs/run_button.md).
+
+**Recipe.**
+
+1. Import packages
+
+```python
+import marimo as mo
+```
+
+2. Create a run button
+
+```python
+button = mo.ui.run_button()
+button
+```
+
+3. Run something only if the button has been clicked.
+
+```python
+mo.stop(not button.value, "Click 'run' to generate a random number")
+
+import random
+random.randint(0, 1000)
+```
+
+
 ### Create a counter button
 
 **Use cases.** A counter button, i.e. a button that counts the number of times

marimo/_plugins/ui/__init__.py

@@ -27,6 +27,7 @@
     "radio",
     "range_slider",
     "refresh",
+    "run_button",
     "slider",
     "switch",
     "table",
@@ -62,6 +63,7 @@
 from marimo._plugins.ui._impl.microphone import microphone
 from marimo._plugins.ui._impl.plotly import plotly
 from marimo._plugins.ui._impl.refresh import refresh
+from marimo._plugins.ui._impl.run_button import run_button
 from marimo._plugins.ui._impl.switch import switch
 from marimo._plugins.ui._impl.table import table
 from marimo._plugins.ui._impl.tabs import tabs

marimo/_plugins/ui/_core/ui_element.py

@@ -379,6 +379,10 @@ def _update(self, value: S) -> None:
         if self._on_change is not None:
             self._on_change(self._value)
 
+    def _on_update_completion(self) -> None:
+        """Callback to run after the kernel has processed a value update."""
+        return
+
     def _clone(self) -> UIElement[S, T]:
         """Clone a UIElement, returning one with a different id
 

marimo/_plugins/ui/_impl/input.py

@@ -990,6 +990,7 @@ def __init__(
     ) -> None:
         self._on_click = (lambda _: value) if on_click is None else on_click
         self._initial_value = value
+        # This should be kept in sync with mo.ui.run_button()
         super().__init__(
             component_name=button._name,
             # frontend's value is always a counter

marimo/_plugins/ui/_impl/run_button.py

@@ -0,0 +1,117 @@
+# Copyright 2024 Marimo. All rights reserved.
+from __future__ import annotations
+
+from typing import Any, Callable, Final, Literal, Optional
+
+from marimo._output.rich_help import mddoc
+from marimo._plugins.ui._core.ui_element import UIElement
+from marimo._plugins.ui._impl.input import button
+from marimo._runtime.context.types import ContextNotInitializedError
+
+
+@mddoc
+class run_button(UIElement[Any, Any]):
+    """
+    A button that can be used to trigger computation.
+
+    **Example.**
+
+    ```python
+    # a button that when clicked will have its value set to True;
+    # any cells referencing that button will automatically run.
+    button = mo.ui.button()
+    button
+    ```
+
+    ```python
+    slider = mo.ui.slider(1, 10)
+    slider
+    ```
+
+    ```python
+    # if the button hasn't been clicked, don't run.
+    mo.stop(not button.value)
+
+    slider.value
+    ```
+
+    When clicked, `run_button`'s value is set to `True`, and any cells
+    referencing it are run. After those cells are run, `run_button`'s
+    value will automatically be set back to `False` as long as automatic
+    execution is enabled.
+
+    **Attributes.**
+
+    - `value`: the value of the button; `True` when clicked, and reset to
+      `False` after cells referencing the button finish running (when
+      automatic execution is enabled).
+
+    **Initialization Args.**
+
+    - `kind`: 'neutral', 'success', 'warn', or 'danger'
+    - `disabled`: whether the button is disabled
+    - `tooltip`: a tooltip to display for the button
+    - `label`: text label for the element
+    - `on_change`: optional callback to run when this element's value changes
+    - `full_width`: whether the input should take up the full width of its
+        container
+    """
+
+    _name: Final[str] = "marimo-button"
+
+    def __init__(
+        self,
+        kind: Literal["neutral", "success", "warn", "danger"] = "neutral",
+        disabled: bool = False,
+        tooltip: Optional[str] = None,
+        *,
+        label: str = "click to run",
+        on_change: Optional[Callable[[Any], None]] = None,
+        full_width: bool = False,
+    ) -> None:
+        self._initial_value = False
+        super().__init__(
+            # We reuse the button plugin on the frontend, since the UI
+            # is the same.
+            component_name=button._name,
+            # frontend's value is a counter
+            initial_value=0,
+            label=label,
+            args={
+                "kind": kind,
+                "disabled": disabled,
+                "tooltip": tooltip,
+                "full-width": full_width,
+            },
+            on_change=on_change,
+        )
+
+    def _convert_value(self, value: Any) -> Any:
+        if value == 0:
+            # frontend's value == 0 only during initialization; first value
+            # frontend will send is 1
+            return False
+        else:
+            return True
+
+    def _on_update_completion(self) -> None:
+        from marimo._runtime.context import get_context
+        from marimo._runtime.context.kernel_context import KernelRuntimeContext
+
+        try:
+            ctx = get_context()
+        except ContextNotInitializedError:
+            self._value = False
+            return
+
+        if isinstance(ctx, KernelRuntimeContext) and ctx.lazy:
+            # Resetting to False in lazy kernels makes the button pointless,
+            # since its value hasn't been read by downstream cells on update
+            # completion.
+            #
+            # The right thing to do would be to somehow set to False after
+            # all cells that were marked stale because of the update were run,
+            # but that's too complicated.
+            return
+        else:
+            self._value = False

marimo/_runtime/context/kernel_context.py

@@ -43,6 +43,10 @@ def globals(self) -> dict[str, Any]:
     def execution_context(self) -> ExecutionContext | None:
         return self._kernel.execution_context
 
+    @property
+    def lazy(self) -> bool:
+        return self._kernel.lazy()
+
     @property
     def cell_id(self) -> Optional[CellId_t]:
         """Get the cell id of the currently executing cell, if any."""