Dictionary

class marimo.ui.dictionary(elements: dict[str, marimo._plugins.ui._core.ui_element.UIElement[Any, Any]], *, label: str = '', on_change: Callable[[dict[str, object]], None] | None = None)

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.

Attributes.

• value: a dict holding the values of the UI elements, keyed by their names.

• elements: a dict of the wrapped elements (clones of the originals)

• on_change: optional callback to run when this element’s value changes

Initialization Args.

• elements: a dict mapping names to UI elements to include

• label: a descriptive name for the dictionary to trigger value updates

Public methods

hstack(**kwargs)	Stack the elements horizontally.
vstack(**kwargs)	Stack the elements vertically.

Inherited from _batch_base

get(key[, default])
items()
values()

Inherited from UIElement

form([label, bordered, loading, ...])	Create a submittable form out of this UIElement.
send_message(message, buffers)	Send a message to the element rendered on the frontend from the backend.

Inherited from Html

batch(**elements)	Convert an HTML object with templated text into a UI element.
center()	Center an item.
right()	Right-justify.
left()	Left-justify.
callout([kind])	Create a callout containing this HTML element.
style([style])	Wrap an object in a styled container.

Public Data Attributes:

Inherited from _batch_base

elements

Inherited from UIElement

value

The element’s current value.

Inherited from Html

text	A string of HTML representing this element.

---

hstack(**kwargs: Any) → Html

Stack the elements horizontally.

For kwargs, see marimo.hstack.

vstack(**kwargs: Any) → Html

Stack the elements vertically.

For kwargs, see marimo.vstack.