Dates¶

Single date¶

    @app.cell
    def __():
        date = mo.ui.date(label="Start Date")
        return

    @app.cell
    def __():
        mo.hstack([date, mo.md(f"Has value: {date.value}")])
        return

marimo.ui.date ¶

date(
    start: Optional[date | str] = None,
    stop: Optional[date | str] = None,
    value: Optional[date | str] = None,
    *,
    label: str = "",
    on_change: Optional[Callable[[date], None]] = None,
    full_width: bool = False
)

Bases: UIElement[str, date]

A date picker with an optional start and stop date.

Examples:

# initialize the date picker at a given date
date = mo.ui.date(value="2022-01-01")

# when value is omitted, date picker initializes with today's date
date = mo.ui.date()

# create a date picker with bounds
date = mo.ui.date(
    value="2022-06-01",
    start="2022-01-01",
    stop="2022-12-31",
)

Or from a dataframe series:

date = mo.ui.date.from_series(df["column_name"])

ATTRIBUTE	DESCRIPTION
`value`	A str (YYYY-MM-DD) or `datetime.date` object of the chosen date. TYPE: `str \| date`
`start`	The start date. TYPE: `date`
`stop`	The stop date. TYPE: `date`

PARAMETER	DESCRIPTION
`start`	Minimum date selectable. If None, defaults to 01-01-0001. TYPE: `date \| str` DEFAULT: `None`
`stop`	Maximum date selectable. If None, defaults to 12-31-9999. TYPE: `date \| str` DEFAULT: `None`
`value`	Default date. If None and start and stop are None, defaults to the current day. If None and start is not None, defaults to start. If None and stop is not None, defaults to stop. TYPE: `date \| str` DEFAULT: `None`
`label`	Markdown label for the element. TYPE: `str` DEFAULT: `''`
`on_change`	Optional callback to run when this element's value changes. TYPE: `Callable[[date], None]` DEFAULT: `None`
`full_width`	Whether the input should take up the full width of its container. TYPE: `bool` DEFAULT: `False`

DATE_FORMAT `class-attribute` `instance-attribute` ¶

DATE_FORMAT = '%Y-%m-%d'

start `property` ¶

start: date

Get the minimum selectable date.

RETURNS	DESCRIPTION
`date`	datetime.date: The start date, which is either the user-specified minimum date or 01-01-0001 if no start date was specified.

stop `property` ¶

stop: date

Get the maximum selectable date.

RETURNS	DESCRIPTION
`date`	datetime.date: The stop date, which is either the user-specified maximum date or 12-31-9999 if no stop date was specified.

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).

Args.

elements: the UI elements to interpolate into the HTML template.

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.

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.

Use this method to create a form that gates the submission of a UIElements value until a submit button is clicked.

The value of the form is the value of the underlying element the last time the form was submitted.

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()
)

Args.

label: A text label for the form.
bordered: whether the form should have a border
loading: whether the form should be in a loading state
submit_button_label: the label of the submit button
submit_button_tooltip: the tooltip of the submit button
submit_button_disabled: whether the submit button should be disabled
clear_on_submit: whether the form should clear its contents after submitting
show_clear_button: whether the form should show a clear button
clear_button_label: the label of the clear button
clear_button_tooltip: the tooltip of the clear button
validate: a function that takes the form's value and returns an error message if the value is invalid, or None if the value is valid

from_series `staticmethod` ¶

from_series(
    series: DataFrameSeries, **kwargs: Any
) -> "date"

Create a date picker from a dataframe series.

PARAMETER	DESCRIPTION
`series`	A pandas Series containing datetime values. TYPE: `DataFrameSeries`
`**kwargs`	Additional keyword arguments passed to the date picker constructor. Supported arguments: start, stop, label, and any other date picker parameters. TYPE: `Any` DEFAULT: `{}`

RETURNS	DESCRIPTION
`date`	A date picker initialized with the series' min and max dates as bounds. TYPE: `'date'`

left ¶

left() -> Html

Left-justify.

Example.

mo.md("# Hello, world").left()

Returns.

An Html object.

right ¶

right() -> Html

Right-justify.

Example.

mo.md("# Hello, world").right()

Returns.

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")

Args.

style: an optional dict of CSS styles, keyed by property name
**kwargs: CSS styles as keyword arguments

:members:

Date and time¶

    @app.cell
    def __():
        datetime = mo.ui.datetime(label="Start Date")
        return

    @app.cell
    def __():
        mo.hstack([datetime, mo.md(f"Has value: {datetime.value}")])
        return

marimo.ui.datetime ¶

datetime(
    start: Optional[datetime | str] = None,
    stop: Optional[datetime | str] = None,
    value: Optional[datetime | str] = None,
    *,
    label: Optional[str] = None,
    on_change: Optional[
        Callable[[Optional[datetime]], None]
    ] = None,
    full_width: bool = False
)

Bases: UIElement[Optional[str], Optional[datetime]]

A datetime picker over an interval.

Examples:

datetime_picker = mo.ui.datetime(
    start=dt.datetime(2023, 1, 1),
    stop=dt.datetime(2023, 12, 31, 23, 59, 59),
)

Or from a dataframe series:

datetime_picker = mo.ui.datetime.from_series(df["datetime_column"])

ATTRIBUTE	DESCRIPTION
`value`	The selected datetime, possibly None. TYPE: `datetime`
`start`	The minimum selectable datetime. TYPE: `datetime`
`stop`	The maximum selectable datetime. TYPE: `datetime`

PARAMETER	DESCRIPTION
`start`	The minimum selectable datetime. Defaults to minimum datetime. TYPE: `datetime \| str` DEFAULT: `None`
`stop`	The maximum selectable datetime. Defaults to maximum datetime. TYPE: `datetime \| str` DEFAULT: `None`
`value`	Default value. TYPE: `datetime \| str` DEFAULT: `None`
`label`	Markdown label for the element. TYPE: `str` DEFAULT: `None`
`on_change`	Optional callback to run when this element's value changes. TYPE: `Callable[[Optional[datetime]], None]` DEFAULT: `None`
`full_width`	Whether the input should take up the full width of its container. TYPE: `bool` DEFAULT: `False`

DATETIME_FORMAT `class-attribute` `instance-attribute` ¶

DATETIME_FORMAT: Final[str] = '%Y-%m-%dT%H:%M:%S'

start `property` ¶

start: datetime

Get the minimum selectable datetime.

RETURNS	DESCRIPTION
`datetime`	datetime.datetime: The start datetime, which is either the user-specified minimum datetime or datetime.min if no start datetime was specified.

stop `property` ¶

stop: datetime

Get the maximum selectable datetime.

RETURNS	DESCRIPTION
`datetime`	datetime.datetime: The stop datetime, which is either the user-specified maximum datetime or datetime.max if no stop datetime was specified.

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).

Args.

elements: the UI elements to interpolate into the HTML template.

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.

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.

Use this method to create a form that gates the submission of a UIElements value until a submit button is clicked.

The value of the form is the value of the underlying element the last time the form was submitted.

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()
)

Args.

label: A text label for the form.
bordered: whether the form should have a border
loading: whether the form should be in a loading state
submit_button_label: the label of the submit button
submit_button_tooltip: the tooltip of the submit button
submit_button_disabled: whether the submit button should be disabled
clear_on_submit: whether the form should clear its contents after submitting
show_clear_button: whether the form should show a clear button
clear_button_label: the label of the clear button
clear_button_tooltip: the tooltip of the clear button
validate: a function that takes the form's value and returns an error message if the value is invalid, or None if the value is valid

from_series `staticmethod` ¶

from_series(
    series: DataFrameSeries, **kwargs: Any
) -> "datetime"

Create a datetime picker from a dataframe series.

PARAMETER	DESCRIPTION
`series`	A pandas Series containing datetime values. TYPE: `DataFrameSeries`
`**kwargs`	Additional keyword arguments passed to the datetime picker constructor. Supported arguments: start, stop, label, and any other datetime picker parameters. TYPE: `Any` DEFAULT: `{}`

RETURNS	DESCRIPTION
`datetime`	A datetime picker initialized with the series' min and max datetimes as bounds. TYPE: `'datetime'`

left ¶

left() -> Html

Left-justify.

Example.

mo.md("# Hello, world").left()

Returns.

An Html object.

right ¶

right() -> Html

Right-justify.

Example.

mo.md("# Hello, world").right()

Returns.

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")

Args.

style: an optional dict of CSS styles, keyed by property name
**kwargs: CSS styles as keyword arguments

:members:

Date range¶

    @app.cell
    def __():
        date_range = mo.ui.date_range(label="Start Date")
        return

    @app.cell
    def __():
        mo.hstack([date_range, mo.md(f"Has value: {date_range.value}")])
        return

marimo.ui.date_range ¶

date_range(
    start: Optional[date | str] = None,
    stop: Optional[date | str] = None,
    value: Optional[
        Tuple[date, date] | Tuple[str, str]
    ] = None,
    *,
    label: Optional[str] = None,
    on_change: Optional[
        Callable[[Tuple[date, date]], None]
    ] = None,
    full_width: bool = False
)

Bases: UIElement[Tuple[str, str], Tuple[date, date]]

A date range picker over an interval.

Examples:

date_range = mo.ui.date_range(
    start=dt.date(2023, 1, 1), stop=dt.date(2023, 12, 31)
)

Or from a dataframe series:

date_range = mo.ui.date_range.from_series(df["date_column"])

ATTRIBUTE	DESCRIPTION
`value`	A tuple of (start_date, end_date) representing the selected range. TYPE: `Tuple[date, date]`
`start`	The minimum selectable date. TYPE: `date`
`stop`	The maximum selectable date. TYPE: `date`

PARAMETER	DESCRIPTION
`start`	Minimum date selectable. If None, defaults to 01-01-0001. TYPE: `date \| str` DEFAULT: `None`
`stop`	Maximum date selectable. If None, defaults to 12-31-9999. TYPE: `date \| str` DEFAULT: `None`
`value`	Default value as (start_date, end_date). If None, defaults to (start, stop) if provided, otherwise today's date for both. TYPE: `Tuple[date \| str, date \| str]` DEFAULT: `None`
`label`	Markdown label for the element. TYPE: `str` DEFAULT: `None`
`on_change`	Optional callback to run when this element's value changes. TYPE: `Callable[[Tuple[date, date]], None]` DEFAULT: `None`
`full_width`	Whether the input should take up the full width of its container. TYPE: `bool` DEFAULT: `False`

DATEFORMAT `class-attribute` `instance-attribute` ¶

DATEFORMAT: Final[str] = '%Y-%m-%d'

start `property` ¶

start: date

Get the minimum selectable date.

RETURNS	DESCRIPTION
`date`	datetime.date: The start date, which is either the user-specified minimum date or 01-01-0001 if no start date was specified.

stop `property` ¶

stop: date

Get the maximum selectable date.

RETURNS	DESCRIPTION
`date`	datetime.date: The stop date, which is either the user-specified maximum date or 12-31-9999 if no stop date was specified.

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).

Args.

elements: the UI elements to interpolate into the HTML template.

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.

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.

Use this method to create a form that gates the submission of a UIElements value until a submit button is clicked.

The value of the form is the value of the underlying element the last time the form was submitted.

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()
)

Args.

label: A text label for the form.
bordered: whether the form should have a border
loading: whether the form should be in a loading state
submit_button_label: the label of the submit button
submit_button_tooltip: the tooltip of the submit button
submit_button_disabled: whether the submit button should be disabled
clear_on_submit: whether the form should clear its contents after submitting
show_clear_button: whether the form should show a clear button
clear_button_label: the label of the clear button
clear_button_tooltip: the tooltip of the clear button
validate: a function that takes the form's value and returns an error message if the value is invalid, or None if the value is valid

from_series `staticmethod` ¶

from_series(
    series: DataFrameSeries, **kwargs: Any
) -> "date_range"

Create a date range picker from a dataframe series.

PARAMETER	DESCRIPTION
`series`	A pandas Series containing datetime values. TYPE: `DataFrameSeries`
`**kwargs`	Additional keyword arguments passed to the date range picker constructor. Supported arguments: start, stop, label, and any other date range picker parameters. TYPE: `Any` DEFAULT: `{}`

RETURNS	DESCRIPTION
`date_range`	A date range picker initialized with the series' min and max dates as bounds. TYPE: `'date_range'`

left ¶

left() -> Html

Left-justify.

Example.

mo.md("# Hello, world").left()

Returns.

An Html object.

right ¶

right() -> Html

Right-justify.

Example.

mo.md("# Hello, world").right()

Returns.

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")

Args.

style: an optional dict of CSS styles, keyed by property name
**kwargs: CSS styles as keyword arguments

:members:

Dates¶

Single date¶

marimo.ui.date ¶

DATE_FORMAT class-attribute instance-attribute ¶

start property ¶

stop property ¶

text property ¶

value property writable ¶

batch ¶

callout ¶

center ¶

form ¶

from_series staticmethod ¶

left ¶

right ¶

send_message ¶

style ¶

Date and time¶

marimo.ui.datetime ¶

DATETIME_FORMAT class-attribute instance-attribute ¶

start property ¶

stop property ¶

text property ¶

value property writable ¶

batch ¶

callout ¶

center ¶

form ¶

from_series staticmethod ¶

left ¶

right ¶

send_message ¶

style ¶

Date range¶

marimo.ui.date_range ¶

DATEFORMAT class-attribute instance-attribute ¶

start property ¶

stop property ¶

text property ¶

value property writable ¶

batch ¶

callout ¶

center ¶

form ¶

from_series staticmethod ¶

left ¶

right ¶

send_message ¶

style ¶

DATE_FORMAT `class-attribute` `instance-attribute` ¶

start `property` ¶

stop `property` ¶

text `property` ¶

value `property` `writable` ¶

from_series `staticmethod` ¶

DATETIME_FORMAT `class-attribute` `instance-attribute` ¶

start `property` ¶

stop `property` ¶

text `property` ¶

value `property` `writable` ¶

from_series `staticmethod` ¶

DATEFORMAT `class-attribute` `instance-attribute` ¶

start `property` ¶

stop `property` ¶

text `property` ¶

value `property` `writable` ¶

from_series `staticmethod` ¶