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

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`

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	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: `{}`

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` ¶