Table¶

marimo.ui.table ¶

table(
    data: Union[
        ListOrTuple[
            Union[str, int, float, bool, MIME, None]
        ],
        ListOrTuple[Dict[str, JSONType]],
        Dict[str, ListOrTuple[JSONType]],
        "IntoDataFrame",
    ],
    pagination: Optional[bool] = None,
    selection: Optional[
        Literal["single", "multi"]
    ] = "multi",
    page_size: int = 10,
    show_column_summaries: Optional[
        Union[bool, Literal["stats", "chart"]]
    ] = None,
    format_mapping: Optional[
        Dict[str, Union[str, Callable[..., Any]]]
    ] = None,
    freeze_columns_left: Optional[Sequence[str]] = None,
    freeze_columns_right: Optional[Sequence[str]] = None,
    text_justify_columns: Optional[
        Dict[str, Literal["left", "center", "right"]]
    ] = None,
    wrapped_columns: Optional[List[str]] = None,
    show_download: bool = True,
    max_columns: Optional[int] = 50,
    *,
    label: str = "",
    on_change: Optional[
        Callable[
            [
                Union[
                    List[JSONType],
                    Dict[str, ListOrTuple[JSONType]],
                    "IntoDataFrame",
                ]
            ],
            None,
        ]
    ] = None,
    _internal_column_charts_row_limit: Optional[int] = None,
    _internal_summary_row_limit: Optional[int] = None,
    _internal_total_rows: Optional[
        Union[int, Literal["too_many"]]
    ] = None
)

Bases: UIElement[List[str], Union[List[JSONType], IntoDataFrame]]

A table component with selectable rows.

Get the selected rows with table.value. The table data can be supplied as:

a list of dicts, with one dict for each row, keyed by column names;
a list of values, representing a table with a single column;
a Pandas dataframe; or
a Polars dataframe; or
an Ibis dataframe; or
a PyArrow table.

Examples:

Create a table from a list of dicts, one for each row:

table = mo.ui.table(
    data=[
        {"first_name": "Michael", "last_name": "Scott"},
        {"first_name": "Dwight", "last_name": "Schrute"},
    ],
    label="Users",
)

Create a table from a single column of data:

table = mo.ui.table(
    data=[
        {"first_name": "Michael", "last_name": "Scott"},
        {"first_name": "Dwight", "last_name": "Schrute"},
    ],
    label="Users",
)

Create a table from a dataframe:

# df is a Pandas or Polars dataframe
table = mo.ui.table(
    data=df,
    # use pagination when your table has many rows
    pagination=True,
    label="Dataframe",
)

Create a table with format mapping:

# format_mapping is a dict keyed by column names,
# with values as formatting functions or strings
def format_name(name):
    return name.upper()


table = mo.ui.table(
    data=[
        {"first_name": "Michael", "last_name": "Scott", "age": 45},
        {"first_name": "Dwight", "last_name": "Schrute", "age": 40},
    ],
    format_mapping={
        "first_name": format_name,  # Use callable to format first names
        "age": "{:.1f}".format,  # Use string format for age
    },
    label="Format Mapping",
)

In each case, access the table data with table.value.

ATTRIBUTE	DESCRIPTION
`value`	The selected rows, in the same format as the original data, or None if no selection. TYPE: `Union[List[JSONType], IntoDataFrame]`
`data`	The original table data. TYPE: `Union[List[JSONType], IntoDataFrame]`

PARAMETER	DESCRIPTION
`data`	Values can be primitives (`str`, `int`, `float`, `bool`, or `None`) or marimo elements: e.g. `mo.ui.button(...)`, `mo.md(...)`, `mo.as_html(...)`, etc. Data can be passed in many ways: - as dataframes: a pandas dataframe, a polars dataframe - as rows: a list of dicts, where each dict represents a row in the table - as columns: a dict keyed by column names, where the value of each entry is a list representing a column - as a single column: a list of values TYPE: `Union[List[Union[str, int, float, bool, MIME, None]], List[Dict[str, JSONType]], Dict[str, List[JSONType]], IntoDataFrame]`
`pagination`	Whether to paginate; if False, all rows will be shown. Defaults to True when above 10 rows, False otherwise. TYPE: `bool` DEFAULT: `None`
`selection`	'single' or 'multi' to enable row selection, or None to disable. Defaults to "multi". TYPE: `Literal['single', 'multi']` DEFAULT: `'multi'`
`page_size`	The number of rows to show per page. Defaults to 10. TYPE: `int` DEFAULT: `10`
`show_column_summaries`	Whether to show column summaries. Defaults to True when the table has less than 40 columns, False otherwise. If "stats", only show stats. If "chart", only show charts. TYPE: `Union[bool, Literal['stats', 'chart']]` DEFAULT: `None`
`show_download`	Whether to show the download button. Defaults to True for dataframes, False otherwise. TYPE: `bool` DEFAULT: `True`
`format_mapping`	A mapping from column names to formatting strings or functions. TYPE: `Dict[str, Union[str, Callable[..., Any]]]` DEFAULT: `None`
`freeze_columns_left`	List of column names to freeze on the left. TYPE: `Sequence[str]` DEFAULT: `None`
`freeze_columns_right`	List of column names to freeze on the right. TYPE: `Sequence[str]` DEFAULT: `None`
`text_justify_columns`	Dictionary of column names to text justification options: left, center, right. TYPE: `Dict[str, Literal['left', 'center', 'right']]` DEFAULT: `None`
`wrapped_columns`	List of column names to wrap. TYPE: `List[str]` DEFAULT: `None`
`label`	Markdown label for the element. Defaults to "". TYPE: `str` DEFAULT: `''`
`on_change`	Optional callback to run when this element's value changes. TYPE: `Callable[[Union[List[JSONType], Dict[str, List[JSONType]], IntoDataFrame]], None]` DEFAULT: `None`
`max_columns`	Maximum number of columns to display. Defaults to 50. Set to None to show all columns. TYPE: `int` DEFAULT: `50`

data `property` ¶

data: TableData

Get the original table data.

RETURNS	DESCRIPTION
`TableData`	The original data passed to the table constructor, in its original format (list, dict, dataframe, etc.). TYPE: `TableData`

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.

download_as ¶

download_as(args: DownloadAsArgs) -> str

Download the table data in the specified format.

Downloads selected rows if there are any, otherwise downloads all rows. Raw data is downloaded without any formatting applied.

PARAMETER	DESCRIPTION
`args`	Arguments specifying the download format. format must be one of 'csv' or 'json'. TYPE: `DownloadAsArgs`

RETURNS	DESCRIPTION
`str`	URL to download the data file. TYPE: `str`

RAISES	DESCRIPTION
`ValueError`	If format is not 'csv' or 'json'.

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_column_summaries ¶

get_column_summaries(args: EmptyArgs) -> ColumnSummaries

Get statistical summaries for each column in the table.

Calculates summaries like null counts, min/max values, unique counts, etc. for each column. Summaries are only calculated if the total number of rows is below the column summary row limit.

PARAMETER	DESCRIPTION
`args`	Empty arguments object (unused). TYPE: `EmptyArgs`

RETURNS	DESCRIPTION
`ColumnSummaries`	Object containing column summaries and chart data. If summaries are disabled or row limit is exceeded, returns empty summaries with is_disabled flag set appropriately. TYPE: `ColumnSummaries`

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.

search ¶

search(args: SearchTableArgs) -> SearchTableResponse

Search and filter the table data.

Applies filters, search query, and sorting to the table data. Returns paginated results based on the specified page size and number.

PARAMETER	DESCRIPTION
`args`	Search arguments containing: - page_size: Number of rows per page - page_number: Zero-based page index - query: Optional search query string - sort: Optional sorting configuration - filters: Optional list of filter conditions - limit: Optional row limit TYPE: `SearchTableArgs`

RETURNS	DESCRIPTION
`SearchTableResponse`	Response containing: - data: Filtered and formatted table data for the requested page - total_rows: Total number of rows after applying filters TYPE: `SearchTableResponse`

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

Table¶

marimo.ui.table ¶

data property ¶

text property ¶

value property writable ¶

batch ¶

callout ¶

center ¶

download_as ¶

form ¶

get_column_summaries ¶

left ¶

right ¶

search ¶

send_message ¶

style ¶

data `property` ¶

text `property` ¶

value `property` `writable` ¶