Status

Use progress bars or spinners to visualize loading status in your notebooks and apps. Useful when iterating over collections or loading data from files, databases, or APIs.

Progress bar

You can display a progress bar while iterating over a collection, similar to tqdm.

Source code for examples/outputs/progress_bar.py

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

import marimo


app = marimo.App()

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

@app.cell
def _(mo,):
    rerun = mo.ui.button(label="Rerun")
    rerun
    return (rerun,)

@app.cell
async def _(mo, rerun):
    import asyncio
    rerun
    for _ in mo.status.progress_bar(
        range(10),
        title="Loading",
        subtitle="Please wait",
        show_eta=True,
        show_rate=True
    ):
        await asyncio.sleep(0.5)
    return


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

marimo.status.progress_bar

progress_bar(
    collection: Optional[Collection[S | int]] = None,
    *,
    title: Optional[str] = None,
    subtitle: Optional[str] = None,
    completion_title: Optional[str] = None,
    completion_subtitle: Optional[str] = None,
    total: Optional[int] = None,
    show_rate: bool = True,
    show_eta: bool = True,
    remove_on_exit: bool = False,
    disabled: bool = False
)

Iterate over a collection and show a progress bar.

Examples:

for i in mo.status.progress_bar(range(10)):
    ...

You can optionally provide a title and subtitle to show during iteration, and a title/subtitle to show upon completion:

with mo.status.progress_bar(total=10) as bar:
    for i in range(10):
        ...
        bar.update()

The update method accepts the optional keyword arguments increment (defaults to 1), title, and subtitle.

For performance reasons, the progress bar is only updated in the UI every 150ms.

PARAMETER	DESCRIPTION
collection	Optional collection to iterate over. TYPE: Collection[Union[S, int]] DEFAULT: None
title	Optional title. TYPE: str DEFAULT: None
subtitle	Optional subtitle. TYPE: str DEFAULT: None
completion_title	Optional title to show during completion. TYPE: str DEFAULT: None
completion_subtitle	Optional subtitle to show during completion. TYPE: str DEFAULT: None
total	Optional total number of items to iterate over. TYPE: int DEFAULT: None
show_rate	If True, show the rate of progress (items per second). TYPE: bool DEFAULT: True
show_eta	If True, show the estimated time of completion. TYPE: bool DEFAULT: True
remove_on_exit	If True, remove the progress bar from output on exit. TYPE: bool DEFAULT: False
disabled	If True, disable the progress bar. TYPE: bool DEFAULT: False

collection instance-attribute

collection = collection

completion_subtitle instance-attribute

completion_subtitle = completion_subtitle

completion_title instance-attribute

completion_title = completion_title

disabled instance-attribute

disabled = disabled

progress instance-attribute

progress = ProgressBar(
    title=title,
    subtitle=subtitle,
    total=total,
    show_rate=show_rate,
    show_eta=show_eta,
)

remove_on_exit instance-attribute

remove_on_exit = remove_on_exit

step instance-attribute

step = step if isinstance(collection, range) else 1

Spinner

Source code for examples/outputs/spinner.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()


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


@app.cell
def _(mo):
    rerun = mo.ui.button(label="Rerun")
    rerun
    return (rerun,)


@app.cell
async def _(mo, rerun):
    import asyncio

    rerun
    with mo.status.spinner(title="Loading...") as _spinner:
        await asyncio.sleep(1)
        _spinner.update("Almost done")
        await asyncio.sleep(1)
        _spinner.update("Done")
    return (asyncio,)


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

marimo.status.spinner

spinner(
    title: Optional[str] = None,
    subtitle: Optional[str] = None,
    remove_on_exit: bool = True,
)

Show a loading spinner.

Use mo.status.spinner() as a context manager to show a loading spinner. You can optionally pass a title and subtitle.

Examples:

with mo.status.spinner(subtitle="Loading data ...") as _spinner:
    data = expensive_function()
    _spinner.update(subtitle="Crunching numbers ...")
    ...

mo.ui.table(data)

You can also show the spinner without a context manager:

mo.status.spinner(title="Loading ...") if condition else mo.md("Done!")

PARAMETER	DESCRIPTION
title	Optional title. TYPE: str DEFAULT: None
subtitle	Optional subtitle. TYPE: str DEFAULT: None
remove_on_exit	If True, the spinner is removed from output on exit. Defaults to True. TYPE: bool DEFAULT: True

remove_on_exit instance-attribute

remove_on_exit = remove_on_exit

spinner instance-attribute

spinner = Spinner(title=title, subtitle=subtitle)

subtitle instance-attribute

subtitle = subtitle

title instance-attribute

title = title