Skip to content

Data editor

Source code for examples/ui/data_editor.py

Tip: paste this code into an empty cell, and the marimo editor will create cells for you

import marimo

__generated_with = "0.12.9"
app = marimo.App(width="medium")


@app.cell
def _():
    import marimo as mo
    return (mo,)


@app.cell
def _():
    import os
    return (os,)


@app.cell
def _():
    DATA_FILE = "data.csv"
    return (DATA_FILE,)


@app.cell
def _(DATA_FILE, mo, os):
    import polars as pl

    if not os.path.exists(DATA_FILE):
        from vega_datasets import data

        data.cars().to_csv(DATA_FILE)

    editor = mo.ui.data_editor(pl.read_csv(DATA_FILE)).form(bordered=False)
    editor
    return (editor,)


@app.cell(hide_code=True)
def _(mo):
    mo.md("""The following cell writes the updated dataframe to disk when the submit button is clicked.""")
    return


@app.cell
def _(DATA_FILE, editor, mo):
    mo.stop(editor.value is None, mo.md("Submit your changes."))

    editor.value.write_csv(DATA_FILE)
    return


if __name__ == "__main__":
    app.run()

marimo.ui.data_editor

data_editor(
    data: Union[
        RowOrientedData, ColumnOrientedData, IntoDataFrame
    ],
    *,
    pagination: bool = True,
    page_size: int = 50,
    label: str = "",
    on_change: Optional[
        Callable[
            [
                Union[
                    RowOrientedData,
                    ColumnOrientedData,
                    IntoDataFrame,
                ]
            ],
            None,
        ]
    ] = None,
    column_sizing_mode: Literal["auto", "fit"] = "auto"
)

Bases: UIElement[DataEdits, Union[RowOrientedData, ColumnOrientedData, IntoDataFrame]]

A data editor component for editing tabular data.

This component is experimental and intentionally limited in features, if you have any feature requests, please file an issue at https://github.com/marimo-team/marimo/issues.

The data can be supplied as: 1. a Pandas, Polars, or Pyarrow DataFrame 2. a list of dicts, with one dict for each row, keyed by column names 3. a dict of lists, with each list representing a column

Examples:

Create a data editor from a Pandas dataframe:

import pandas as pd

df = pd.DataFrame({"A": [1, 2, 3], "B": ["a", "b", "c"]})
editor = mo.ui.data_editor(data=df, label="Edit Data")

Create a data editor from a list of dicts:

data = [{"A": 1, "B": "a"}, {"A": 2, "B": "a"}, {"A": 3, "B": "c"}]
editor = mo.ui.data_editor(data=data, label="Edit Data")

Create a data editor from a dict of lists:

data = {"A": [1, 2, 3], "B": ["a", "b", "c"]}
editor = mo.ui.data_editor(data=data, label="Edit Data")
ATTRIBUTE DESCRIPTION
value

The current state of the edited data.

TYPE: Union[RowOrientedData, ColumnOrientedData, IntoDataFrame]

data

The original data passed to the editor.

TYPE: Union[RowOrientedData, ColumnOrientedData, IntoDataFrame]

PARAMETER DESCRIPTION
data

The data to be edited. Can be a Pandas dataframe, a list of dicts, or a dict of lists.

TYPE: Union[RowOrientedData, ColumnOrientedData, IntoDataFrame]

label

Markdown label for the element.

TYPE: str DEFAULT: ''

on_change

Optional callback to run when this element's value changes.

TYPE: Optional[Callable] DEFAULT: None

column_sizing_mode

The column sizing mode for the table. auto will size columns based on the content, fit will size columns to fit the view.

TYPE: Literal['auto', 'fit'] DEFAULT: 'auto'

pagination

Whether to use pagination, enabled by default.

TYPE: Optional[bool] DEFAULT: True

page_size

Page size if pagination is in use, 50 by default.

TYPE: Optional[int] DEFAULT: 50

LIMIT class-attribute instance-attribute

LIMIT: Final[int] = 1000

data property

data: Union[
    RowOrientedData, ColumnOrientedData, IntoDataFrame
]

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

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