Array

marimo.ui.array

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

Bases: UIElement[Dict[str, JSONType], Sequence[object]]

An array of UI elements.

Use an array to: - create a dynamic number 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 array (array.value).

The elements in the array can be accessed using square brackets (array[index]) and embedded in other marimo outputs. You can also iterate over the UI elements using the in operator (for element in array).

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

Examples:

A heterogeneous collection of UI elements:

array = mo.ui.array([mo.ui.slider(1, 10), mo.ui.text(), mo.ui.date()])

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

# array.value returns a list with the values of the elements
array.value

Access and output a UI element in the array:

mo.md(f"This is a slider: array[0]")

Some number of UI elements, determined at runtime:

mo.ui.array([mo.ui.slider(1, 10) for _ in range random.randint(4, 8)])

ATTRIBUTE	DESCRIPTION
value	A list containing the values of the array's entries. TYPE: list
elements	A list of the wrapped elements (clones of the originals). TYPE: list

PARAMETER	DESCRIPTION
elements	The UI elements to include. TYPE: Sequence[UIElement]
label	A descriptive name for the array. Defaults to "". TYPE: str DEFAULT: ''
on_change	Optional callback to run when this element's value changes. TYPE: Optional[Callable[[Sequence[object]], None]] DEFAULT: None

elements property

elements: Sequence[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

hstack

hstack(**kwargs: Any) -> Html

Stack the elements horizontally.

PARAMETER	DESCRIPTION
**kwargs	Additional arguments passed to marimo.hstack. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
Html	HTML representation of horizontally stacked elements. TYPE: Html

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

vstack

vstack(**kwargs: Any) -> Html

Stack the elements vertically.

PARAMETER	DESCRIPTION
**kwargs	Additional arguments passed to marimo.vstack. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
Html	HTML representation of vertically stacked elements. TYPE: Html