Matrix¶

marimo.ui.matrix ¶

matrix(
    value: list[list[Numeric]] | ArrayLike,
    *,
    min_value: Numeric
    | list[list[Numeric]]
    | ArrayLike
    | None = None,
    max_value: Numeric
    | list[list[Numeric]]
    | ArrayLike
    | None = None,
    step: Numeric | list[list[Numeric]] | ArrayLike = 1.0,
    disabled: bool | list[list[bool]] | ArrayLike = False,
    symmetric: bool = False,
    scientific: bool = False,
    precision: int | None = None,
    row_labels: list[str] | None = None,
    column_labels: list[str] | None = None,
    debounce: bool = False,
    label: str = ""
)

Bases: UIElement[list[list[Numeric]], list[list[Numeric]]]

An interactive matrix editor.

A matrix UI element in which each entry is a slider: click and drag horizontally on an entry to increment or decrement its value. The matrix can be configured in many ways, including element-wise bounds, element-wise steps, an element-wise disable mask, and symmetry enforcement.

Examples:

Basic usage:

mat = mo.ui.matrix([[1, 0], [0, 1]])
mat

Access the value in another cell with

mat.value

You can specify bounds and a step size as well:

mat = mo.ui.matrix(
    [[1, 0], [0, 1]],
    min_value=-10,
    max_value=10,
    step=0.5,
)

To disable editing of some or all entries, use the disabled argument:

mat = mo.ui.matrix(
    [[1, 0], [0, 1]],
    # Disable editing the diagonal values
    disabled=[[True, False], [False, True]],
)

The value, bounds, step, and disabled arguments can optionally be NumPy arrays, interpreted elementwise.

import numpy as np

mat = mo.ui.matrix(np.eye(2))
mat

np.asarray(mat.value)

ATTRIBUTE	DESCRIPTION
`value`	The current 2D matrix as a nested list. Use `np.asarray(matrix.value)` to convert to a numpy array. TYPE: `list[list[Numeric]]`

PARAMETER	DESCRIPTION
`value`	Initial 2D matrix data. Accepts a nested list of numbers or a numpy array. Rows and columns are inferred from the shape. TYPE: `list[list[Numeric]] \| ArrayLike`
`min_value`	Minimum allowed value. A scalar is broadcast to all cells; a nested list or numpy array sets per-element bounds. None means unbounded. Defaults to None. TYPE: `Numeric \| list[list[Numeric]] \| ArrayLike \| None` DEFAULT: `None`
`max_value`	Maximum allowed value. A scalar is broadcast to all cells; a nested list or numpy array sets per-element bounds. None means unbounded. Defaults to None. TYPE: `Numeric \| list[list[Numeric]] \| ArrayLike \| None` DEFAULT: `None`
`step`	Drag increment. A scalar is broadcast to all cells; a nested list or numpy array sets per-element step sizes. Defaults to 1.0. TYPE: `Numeric \| list[list[Numeric]] \| ArrayLike` DEFAULT: `1.0`
`disabled`	Whether cells are disabled. A scalar bool is broadcast to all cells; a nested list or numpy bool array sets a per-element mask. Defaults to False. TYPE: `bool \| list[list[bool]] \| ArrayLike` DEFAULT: `False`
`symmetric`	If True, editing cell `[i][j]` also updates cell `[j][i]`. Requires a square matrix. Defaults to False. TYPE: `bool` DEFAULT: `False`
`scientific`	If True, display values in scientific notation (e.g., `1.0e-4`). Defaults to False. TYPE: `bool` DEFAULT: `False`
`precision`	Number of decimal places displayed. When None, inferred from the data values and step sizes. Defaults to None. TYPE: `int \| None` DEFAULT: `None`
`row_labels`	Labels for each row. Defaults to None. TYPE: `list[str] \| None` DEFAULT: `None`
`column_labels`	Labels for each column. Defaults to None. TYPE: `list[str] \| None` DEFAULT: `None`
`debounce`	If True, value updates are only sent to the backend on mouse-up (pointer release) instead of on every drag movement. Useful when the matrix drives expensive downstream computations. Defaults to False. TYPE: `bool` DEFAULT: `False`
`label`	Markdown/LaTeX label for the element. Defaults to "". TYPE: `str` DEFAULT: `''`

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: str | None = None,
    submit_button_disabled: bool = False,
    clear_on_submit: bool = False,
    show_clear_button: bool = False,
    clear_button_label: str = "Clear",
    clear_button_tooltip: str | None = None,
    validate: Callable[[Optional[JSONType]], str | None]
    | None = None,
    on_change: Callable[[Optional[T]], None] | 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.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: `str \| None` 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: `str \| None` DEFAULT: `None`
`validate`	A function that takes the form's value and returns an error message if invalid, or `None` if valid. TYPE: `Callable[[Optional[JSONType]], str \| None] \| None` DEFAULT: `None`
`on_change`	Optional callback to run when this element's value changes. Defaults to None. TYPE: `Callable[[Optional[T]], None] \| None` DEFAULT: `None`

from_args `classmethod` ¶

from_args(
    data: dict[str, int],
    args: InitializationArgs[S, T],
    memo: dict[int, Any] | None = None,
    basis: UIElement[S, T] | None = None,
) -> UIElement[S, T]

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.

style ¶

style(
    style: dict[str, Any] | None = 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: `dict[str, Any] \| None` DEFAULT: `None`
`**kwargs`	CSS styles as keyword arguments TYPE: `Any` DEFAULT: `{}`

Matrix¶

marimo.ui.matrix ¶

text property ¶

value property writable ¶

batch ¶

callout ¶

center ¶

form ¶

from_args classmethod ¶

left ¶

right ¶

style ¶

text `property` ¶

value `property` `writable` ¶

from_args `classmethod` ¶