Dictionary¶

marimo.ui.dictionary ¶

dictionary(
    elements: dict[str, UIElement[Any, Any]],
    *,
    label: str = "",
    on_change: Optional[
        Callable[[dict[str, object]], None]
    ] = None
)

Bases: _batch_base

A dictionary of UI elements.

Use a dictionary to: - create a set of UI elements at runtime - group together logically related UI elements - keep the number of global variables in your program small

Access the values of the elements using the value attribute of the dictionary. The elements in the dictionary can be accessed using square brackets (dictionary[key]) and embedded in other marimo outputs. You can also iterate over the UI elements using the same syntax used for Python dicts.

Note

The UI elements in the dictionary are clones of the original elements: interacting with the dictionary will not update the original elements, and vice versa.

The main reason to use mo.ui.dictionary is for reactive execution — when you interact with an element in a mo.ui.dictionary, all cells that reference the mo.ui.dictionary run automatically, just like all other ui elements. When you use a regular dictionary, you don't get this reactivity.

Examples:

A heterogeneous collection of UI elements:

d = mo.ui.dictionary(
    {
        "slider": mo.ui.slider(1, 10),
        "text": mo.ui.text(),
        "date": mo.ui.date(),
    }
)

Get the values of the slider, text, and date elements via d.value:

# d.value returns a dict with keys "slider", "text", "date"
d.value

Access and output a UI element in the array:

mo.md(f"This is a slider: {d['slider']}")

Some number of UI elements, determined at runtime:

mo.ui.dictionary(
    {
        f"option {i}": mo.ui.slider(1, 10)
        for i in range(random.randint(4, 8))
    }
)

Quick layouts of UI elements:

mo.ui.dictionary(
    {
        f"option {i}": mo.ui.slider(1, 10)
        for i in range(random.randint(4, 8))
    }
).vstack()  # Can also use `hstack`, `callout`, `center`, etc.

ATTRIBUTE	DESCRIPTION
`value`	A dict holding the values of the UI elements, keyed by their names. TYPE: `dict`
`elements`	A dict of the wrapped elements (clones of the originals). TYPE: `dict`
`on_change`	Optional callback to run when this element's value changes. TYPE: `Optional[Callable[[dict[str, object]], None]]`

PARAMETER	DESCRIPTION
`elements`	A dict mapping names to UI elements to include. TYPE: `dict[str, UIElement[Any, Any]]`
`label`	A descriptive name for the dictionary. Defaults to "". TYPE: `str` DEFAULT: `''`

elements `property` ¶

elements: dict[str, UIElement[JSONType, object]]

text `property` ¶

text: str

A string of HTML representing this element.

value `property` `writable` ¶

value: T

The element's current value.

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).

Args.

elements: the UI elements to interpolate into the HTML template.

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.

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.

Use this method to create a form that gates the submission of a UIElements value until a submit button is clicked.

The value of the form is the value of the underlying element the last time the form was submitted.

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()
)

Args.

label: A text label for the form.
bordered: whether the form should have a border
loading: whether the form should be in a loading state
submit_button_label: the label of the submit button
submit_button_tooltip: the tooltip of the submit button
submit_button_disabled: whether the submit button should be disabled
clear_on_submit: whether the form should clear its contents after submitting
show_clear_button: whether the form should show a clear button
clear_button_label: the label of the clear button
clear_button_tooltip: the tooltip of the clear button
validate: a function that takes the form's value and returns an error message if the value is invalid, or None if the value is valid

get ¶

get(key: str, default: Any | None = None) -> Any

Get a UI element by key with an optional default value.

PARAMETER	DESCRIPTION
`key`	The key to look up in the batch. TYPE: `str`
`default`	Value to return if key is not found. Defaults to None. TYPE: `Any \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Any`	The UI element if found, otherwise the default value. TYPE: `Any`

hstack ¶

hstack(**kwargs: Any) -> Html

Stack the elements horizontally.

For kwargs, see marimo.hstack.

items ¶

items() -> ItemsView[str, UIElement[JSONType, object]]

Return a view of the batch's items (key-value pairs).

RETURNS	DESCRIPTION
`ItemsView[str, UIElement[JSONType, object]]`	ItemsView[str, UIElement]: A view of the batch's (key, element) pairs.

left ¶

left() -> Html

Left-justify.

Example.

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

Returns.

An Html object.

right ¶

right() -> Html

Right-justify.

Example.

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

Returns.

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")

Args.

style: an optional dict of CSS styles, keyed by property name
**kwargs: CSS styles as keyword arguments

values ¶

values() -> ValuesView[UIElement[JSONType, object]]

Return a view of the batch's values (UI elements).

RETURNS	DESCRIPTION
`ValuesView[UIElement[JSONType, object]]`	ValuesView[UIElement]: A view of the batch's UI elements.

vstack ¶

vstack(**kwargs: Any) -> Html

Stack the elements vertically.

For kwargs, see marimo.vstack.

Dictionary¶

marimo.ui.dictionary ¶

elements property ¶

text property ¶

value property writable ¶

batch ¶

callout ¶

center ¶

form ¶

get ¶

hstack ¶

items ¶

left ¶

right ¶

send_message ¶

style ¶

values ¶

vstack ¶

elements `property` ¶

text `property` ¶

value `property` `writable` ¶