Building custom UI elements¶

Build custom UI plugins that hook into marimo's reactive execution engine by using anywidget.

anywidget is a Python library and specification for creating custom Jupyter-compatible widgets. marimo supports anywidget, allowing you to import anywidget widgets or create your own custom widgets and use them in your notebooks and apps.

You can use anywidgets that others have built, such as quak or drawdata, directly in marimo.

Here is an example using drawdata:

# pip install drawdata
from drawdata import ScatterWidget

widget = mo.ui.anywidget(ScatterWidget())

# In another cell, you can access the widget's value
widget.value

# You can also access the widget's specific properties
widget.data
widget.data_as_polars

For additional examples, see our repo.

import anywidget
import traitlets
import marimo as mo

class CounterWidget(anywidget.AnyWidget):
  # Widget front-end JavaScript code
  _esm = """
    function render({ model, el }) {
      let getCount = () => model.get("count");
      let button = document.createElement("button");
      button.innerHTML = `count is ${getCount()}`;
      button.addEventListener("click", () => {
        model.set("count", getCount() + 1);
        model.save_changes();
      });
      model.on("change:count", () => {
        button.innerHTML = `count is ${getCount()}`;
      });
      el.appendChild(button);
    }
    export default { render };
  """
  _css = """
    button {
      padding: 5px !important;
      border-radius: 5px !important;
      background-color: #f0f0f0 !important;

      &:hover {
        background-color: lightblue !important;
        color: white !important;
      }
    }
  """

  # Stateful property that can be accessed by JavaScript & Python
  count = traitlets.Int(0).tag(sync=True)

widget = mo.ui.anywidget(CounterWidget())


# In another cell, you can access the widget's value
widget.value

# You can also access the widget's specific properties
widget.count

marimo.ui.anywidget ¶

anywidget(widget: 'AnyWidget')

Bases: UIElement[T, T]

Create a UIElement from an AnyWidget.

This proxies all the widget's attributes and methods, allowing seamless integration of AnyWidget instances with Marimo's UI system.

Examples:

from drawdata import ScatterWidget
import marimo as mo

scatter = ScatterWidget()
scatter = mo.ui.anywidget(scatter)

# In another cell, access its value
# This works for all widgets
scatter.value

# Or attributes specifically on the ScatterWidget
scatter.data_as_pandas
scatter.data_as_polars

ATTRIBUTE	DESCRIPTION
`value`	The value of the widget's traits as a dictionary. TYPE: `Dict[str, Any]`
`widget`	The widget being wrapped. TYPE: `AnyWidget`

PARAMETER	DESCRIPTION
`widget`	The widget to wrap. TYPE: `AnyWidget`

text `property` ¶

text: str

A string of HTML representing this element.

value `property` `writable` ¶

value: T

The element's current value.

widget `instance-attribute` ¶

widget = widget

batch ¶

batch(**elements: UIElement[JSONType, object]) -> batch

Convert an HTML object with templated text into a UI element.

This method lets you create custom UI elements that are represented by arbitrary HTML.

Example

user_info = mo.md(
    '''
    - What's your name?: {name}
    - When were you born?: {birthday}
    '''
).batch(name=mo.ui.text(), birthday=mo.ui.date())

In this example, user_info is a UI Element whose output is markdown and whose value is a dict with keys 'name' and 'birthday' (and values equal to the values of their corresponding elements).

PARAMETER	DESCRIPTION
`elements`	the UI elements to interpolate into the HTML template. TYPE: `UIElement[JSONType, object]` DEFAULT: `{}`

callout ¶

callout(
    kind: Literal[
        "neutral", "danger", "warn", "success", "info"
    ] = "neutral"
) -> Html

Create a callout containing this HTML element.

A callout wraps your HTML element in a raised box, emphasizing its importance. You can style the callout for different situations with the kind argument.

Examples:

mo.md("Hooray, you did it!").callout(kind="success")

mo.md("It's dangerous to go alone!").callout(kind="warn")

center ¶

center() -> Html

Center an item.

Example

mo.md("# Hello, world").center()

RETURNS	DESCRIPTION
`Html`	An `Html` object.

form ¶

form(
    label: str = "",
    *,
    bordered: bool = True,
    loading: bool = False,
    submit_button_label: str = "Submit",
    submit_button_tooltip: Optional[str] = None,
    submit_button_disabled: bool = False,
    clear_on_submit: bool = False,
    show_clear_button: bool = False,
    clear_button_label: str = "Clear",
    clear_button_tooltip: Optional[str] = None,
    validate: Optional[
        Callable[[Optional[JSONType]], Optional[str]]
    ] = None,
    on_change: Optional[
        Callable[[Optional[T]], None]
    ] = None
) -> form[S, T]

Create a submittable form out of this UIElement.

Creates a form that gates submission of a UIElement's value until a submit button is clicked. The form's value is the value of the underlying element from the last submission.

Examples:

Convert any UIElement into a form:

prompt = mo.ui.text_area().form()

Combine with HTML.batch to create a form made out of multiple UIElements:

form = (
    mo.ui.md(
        '''
    **Enter your prompt.**

    {prompt}

    **Choose a random seed.**

    {seed}
    '''
    )
    .batch(
        prompt=mo.ui.text_area(),
        seed=mo.ui.number(),
    )
    .form()
)

PARAMETER	DESCRIPTION
`label`	A text label for the form. TYPE: `str` DEFAULT: `''`
`bordered`	Whether the form should have a border. TYPE: `bool` DEFAULT: `True`
`loading`	Whether the form should be in a loading state. TYPE: `bool` DEFAULT: `False`
`submit_button_label`	The label of the submit button. TYPE: `str` DEFAULT: `'Submit'`
`submit_button_tooltip`	The tooltip of the submit button. TYPE: `Optional[str]` DEFAULT: `None`
`submit_button_disabled`	Whether the submit button should be disabled. TYPE: `bool` DEFAULT: `False`
`clear_on_submit`	Whether the form should clear its contents after submitting. TYPE: `bool` DEFAULT: `False`
`show_clear_button`	Whether the form should show a clear button. TYPE: `bool` DEFAULT: `False`
`clear_button_label`	The label of the clear button. TYPE: `str` DEFAULT: `'Clear'`
`clear_button_tooltip`	The tooltip of the clear button. TYPE: `Optional[str]` DEFAULT: `None`
`validate`	A function that takes the form's value and returns an error message if invalid, or `None` if valid. TYPE: `Optional[Callable[[Optional[JSONType]], Optional[str]]]` DEFAULT: `None`
`on_change`	A callback that takes the form's value and returns an error message if invalid, or `None` if valid. TYPE: `Optional[Callable[[Optional[T]], None]]` DEFAULT: `None`

left ¶

left() -> Html

Left-justify.

Example

mo.md("# Hello, world").left()

RETURNS	DESCRIPTION
`Html`	An `Html` object.

right ¶

right() -> Html

Right-justify.

Example

mo.md("# Hello, world").right()

RETURNS	DESCRIPTION
`Html`	An `Html` object.

send_message ¶

send_message(
    message: Dict[str, object],
    buffers: Optional[Sequence[bytes]],
) -> None

Send a message to the element rendered on the frontend from the backend.

style ¶

style(
    style: Optional[dict[str, Any]] = None, **kwargs: Any
) -> Html

Wrap an object in a styled container.

Example

mo.md("...").style({"max-height": "300px", "overflow": "auto"})
mo.md("...").style(max_height="300px", overflow="auto")

PARAMETER	DESCRIPTION
`style`	an optional dict of CSS styles, keyed by property name TYPE: `Optional[dict[str, Any]]` DEFAULT: `None`
`**kwargs`	CSS styles as keyword arguments TYPE: `Any` DEFAULT: `{}`

Building custom UI elements¶

Importing a widget¶

Custom widget¶

marimo.ui.anywidget ¶

text `property` ¶

value `property` `writable` ¶

widget `instance-attribute` ¶

batch ¶

callout ¶

center ¶

form ¶

left ¶

right ¶

send_message ¶

style ¶

Building custom UI elements¶

Importing a widget¶

Custom widget¶

marimo.ui.anywidget ¶

text property ¶

value property writable ¶

widget instance-attribute ¶

batch ¶

callout ¶

center ¶

form ¶

left ¶

right ¶

send_message ¶

style ¶

text `property` ¶

value `property` `writable` ¶

widget `instance-attribute` ¶