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.
Importing a widget¶
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.
Custom widget¶
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
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. |
widget |
The widget being wrapped.
TYPE:
|
| PARAMETER | DESCRIPTION |
|---|---|
widget
|
The widget to wrap.
TYPE:
|
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:
|
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:
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:
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:
|
bordered
|
Whether the form should have a border.
TYPE:
|
loading
|
Whether the form should be in a loading state.
TYPE:
|
submit_button_label
|
The label of the submit button.
TYPE:
|
submit_button_tooltip
|
The tooltip of the submit button. |
submit_button_disabled
|
Whether the submit button should be disabled.
TYPE:
|
clear_on_submit
|
Whether the form should clear its contents after submitting.
TYPE:
|
show_clear_button
|
Whether the form should show a clear button.
TYPE:
|
clear_button_label
|
The label of the clear button.
TYPE:
|
clear_button_tooltip
|
The tooltip of the clear button. |
validate
|
A function that takes the form's value and returns an error message if invalid,
or
TYPE:
|
on_change
|
Optional callback to run when this element's value changes. Defaults to None. |
classmethod
¶
from_args(data: dict[str, int], args: InitializationArgs[S, T], memo: dict[int, Any] | None = None, basis: UIElement[S, T] | None = None) -> UIElement[S, T]
Send a message to the element rendered on the frontend from the backend.