Batch

marimo.ui.batch

batch(
    html: Html,
    elements: dict[str, UIElement[Any, Any]],
    on_change: Optional[
        Callable[[dict[str, object]], None]
    ] = None,
)

Bases: _batch_base

Convert an HTML object with templated text into a UI element.

A batch is a UI element that wraps other UI elements, and is represented by custom HTML or markdown. You can create a batch by calling the batch() method on Html objects.

Get the value of the wrapped UI elements using the value attribute of the batch.

Examples:

In the below 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).

user_info = mo.md(
    '''
    - What's your name?: {name}
    - When were you born?: {birthday}
    '''
).batch(name=mo.ui.text(), birthday=mo.ui.date())

To get the value of name and birthday, use:

user_info.value

You can also instantiate this class directly:

markdown = mo.md(
    '''
    - What's your name?: {name}
    - When were you born?: {birthday}
    '''
)
batch = mo.ui.batch(
    markdown, {"name": mo.ui.text(), "birthday": mo.ui.date()}
)

ATTRIBUTE	DESCRIPTION
value	A dict of the batched elements' values. TYPE: dict
elements	A dict of the batched elements (clones of the originals). TYPE: dict
on_change	Optional callback to run when this element's value changes. TYPE: Optional[Callable]

PARAMETER	DESCRIPTION
html	A templated Html object. TYPE: Html
elements	The UI elements to interpolate into the HTML template. TYPE: dict[str, UIElement]
on_change	Optional callback to run when this element's value changes. TYPE: Optional[Callable[[Dict[str, object]], None]] DEFAULT: None

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

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.