<!-- Source: https://docs.marimo.io/api/inputs/matrix/ -->

# Matrix

[Interactive marimo example](https://marimo.app/?embed=true&mode=edit&show-chrome=false#code/JYWwDg9gTgLgBCAhlUEBQixjgXgc1AOgEEsAKAd2ABMYALHAIhAFNrgBXERgSjTQACmMIQDGLADYS01FgDM4AfUVkeALjRwtcUJFj4UICHEQBnBOm1woLGBygA7QcLGTpshctUarSGCgAPXAtCDmBCP0CyTSttAG04gEYAGjgABlS0gF1UuIy4FPScuDzM1MSsnJjYhGAHRQA3RAkOFhwAWgBWZOrYpADG5tacbt6rUxgWMBw0whSx7TAbUWBTYAgHHHmarQlEACNJJgASAEljxh6rPl9Ef2AA3ps7R34hLFcpGXklFXVeyIPQhNFosJ62exOIA)

`mo.ui.matrix` also supports 1D (vector) input:

[Interactive marimo example](https://marimo.app/?embed=true&mode=edit&show-chrome=false#code/JYWwDg9gTgLgBCAhlUEBQixjgXgc1AOgEEsAKAd2ABMYALHAIhAFNrgBXERgSjTQACmMIQDGLADYS01FgDM4AfUVkeALjRwtcUJFj4UICHEQBnBOm1woLGBygA7QcLGTpshctUarANxaiMNC4FoQcwIRIMCgAHmSaVtoA2gCMADRwAAwZ2Vk5ALppCYkIwA6KvogSHCw4ALQArEUlWkgxFVU1OE3FiaYwLGA4mYTpvVZgNqLApsAQDjhjLXASiABGkkwAJAA6O-6iAN6+AL5bjM3afH4BQVC9NnaO-EJYrlIy8koq6r0Hd4RKtUWA9bPYnEA)

## marimo.ui.matrix

```python
matrix(
    value: list[list[Numeric]] | list[Numeric] | ArrayLike,
    *,
    min_value: Numeric
    | list[list[Numeric]]
    | list[Numeric]
    | ArrayLike
    | None = None,
    max_value: Numeric
    | list[list[Numeric]]
    | list[Numeric]
    | ArrayLike
    | None = None,
    step: Numeric
    | list[list[Numeric]]
    | list[Numeric]
    | ArrayLike = 1.0,
    disabled: bool
    | list[list[bool]]
    | 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]] | list[Numeric]]`

An interactive matrix/vector 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. These
configuration values may be any array-like object, including as lists,
NumPy arrays, or torch Tensors.

Supports both 2D (matrix) and 1D (vector) inputs. When a flat list is
passed, the element displays as a column vector and `.value` returns a flat
list.

Examples:

Basic 2D matrix:

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

Access the value in another cell with

```python
mat.value  # [[1, 0], [0, 1]]
```

Column vector (1D input):

```python
v = mo.ui.matrix([1, 2, 3])
v.value  # [1, 2, 3]
```

Row vecto

```python
v = mo.ui.matrix([[1, 2, 3]])
v.value  # [[1, 2, 3]]
```

You can specify bounds and a step size as well:

```python
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:

```python
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.

```python
import numpy as np

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

```text
np.asarray(mat.value)
```

| ATTRIBUTE | DESCRIPTION |
| --- | --- |
| `[value](#marimo.ui.matrix.value)` | The current matrix as a nested list, or a flat list when created with 1D input. Use `np.asarray(matrix.value)` to convert to a numpy array. **TYPE:** `list[list[Numeric]] \| list[Numeric]` |

| PARAMETER | DESCRIPTION |
| --- | --- |
| `value` | Initial data. A nested list or 2D array creates a matrix; a flat list or 1D array creates a column vector. Rows and columns are inferred from the shape. **TYPE:** `list[list[Numeric]] \| list[Numeric] \| ArrayLike` |
| `min_value` | Minimum allowed value. A scalar is broadcast to all cells; a list or numpy array sets per-element bounds. For 1D input, accepts a flat list. None means unbounded. Defaults to None. **TYPE:** `Numeric \| list[list[Numeric]] \| list[Numeric] \| ArrayLike \| None` **DEFAULT:** `None` |
| `max_value` | Maximum allowed value. A scalar is broadcast to all cells; a list or numpy array sets per-element bounds. For 1D input, accepts a flat list. None means unbounded. Defaults to None. **TYPE:** `Numeric \| list[list[Numeric]] \| list[Numeric] \| ArrayLike \| None` **DEFAULT:** `None` |
| `step` | Drag increment. A scalar is broadcast to all cells; a list or numpy array sets per-element step sizes. For 1D input, accepts a flat list. Defaults to 1.0. **TYPE:** `Numeric \| list[list[Numeric]] \| list[Numeric] \| ArrayLike` **DEFAULT:** `1.0` |
| `disabled` | Whether cells are disabled. A scalar bool is broadcast to all cells; a list or numpy bool array sets a per-element mask. For 1D input, accepts a flat list. Defaults to False. **TYPE:** `bool \| list[list[bool]] \| 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`

```python
text: str
```

A string of HTML representing this element.

### value `property` `writable`

```python
value: T
```

The element's current value.

### batch

```python
batch(**elements: UIElement[Any, Any]) -> 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**
>
> ```python3
> 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[Any, Any]` **DEFAULT:** `{}` |

### callout

```python
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:

```python3
mo.md("Hooray, you did it!").callout(kind="success")
```

```python3
mo.md("It's dangerous to go alone!").callout(kind="warn")
```

### center

```python
center() -> Html
```

Center an item.

> **Example**
>
> ```python3
> mo.md("# Hello, world").center()
> ```

| RETURNS | DESCRIPTION |
| --- | --- |
| `[Html](https://docs.marimo.io/api/html/#marimo.Html)` | An `Html` object. |

### form

```python
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[[JSONType | None], str | None]
    | None = None,
    on_change: Callable[[T | None], 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:
```python
prompt = mo.ui.text_area().form()
```

Combine with `HTML.batch` to create a form made out of multiple `UIElements`:
```python
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[[JSONType \| None], str \| None] \| None` **DEFAULT:** `None` |
| `on_change` | Optional callback to run when this element's value changes. Defaults to None. **TYPE:** `Callable[[T \| None], None] \| None` **DEFAULT:** `None` |

### from\_args `classmethod`

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

```python
left() -> Html
```

Left-justify.

> **Example**
>
> ```python3
> mo.md("# Hello, world").left()
> ```

| RETURNS | DESCRIPTION |
| --- | --- |
| `[Html](https://docs.marimo.io/api/html/#marimo.Html)` | An `Html` object. |

### right

```python
right() -> Html
```

Right-justify.

> **Example**
>
> ```python3
> mo.md("# Hello, world").right()
> ```

| RETURNS | DESCRIPTION |
| --- | --- |
| `[Html](https://docs.marimo.io/api/html/#marimo.Html)` | An `Html` object. |

### style

```python
style(
    style: dict[str, Any] | None = None, **kwargs: Any
) -> Html
```

Wrap an object in a styled container.

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