Skip to content

Dates

Single date

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

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

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

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

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

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

:members:

Date range

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

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

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

:members: