Fix: mo.ui.refresh typing and docs

[akshayka]

The value of ui.refresh is typically a string, but it was documented to be an int.

The value was weird in that it started as an int of 0, then changed to ' (number of refreshes)`.

Rather than keep this initialization behavior, this change updates ui.refresh's initial value to be an empty string. This is a breaking change, but at least they are both false-y.

This change also updates typing and docs to say the value is a str.

Fixes #9213

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	Apr 16, 2026 5:24pm

[kirangadhave]

🚀

[Copilot]

Pull request overview

This PR updates the mo.ui.refresh UI element to reflect its actual runtime behavior: the element’s value is treated as a string (not an int), and the initial value is changed from 0 to "" to match the frontend’s emitted values and the updated documentation.

Changes:

• Change refresh typing from UIElement[int, int] to UIElement[str, str] and update _convert_value / on_change typing accordingly.
• Update refresh.value documentation to describe the "<interval> (<count>)" string format.
• Change the element’s initial_value from 0 to "".

Comments suppressed due to low confidence (1)

marimo/_plugins/ui/_impl/refresh.py:93

• The logic uses truthiness checks on default_interval (if default_interval ..., [default_interval] if default_interval else [], and the membership check). This means falsy-but-valid values (e.g. 0, 0.0, or even invalid falsy values like []) bypass validation and change behavior (e.g. default_interval=0 won’t be included in options or checked for membership). Consider switching these conditions to explicit default_interval is not None (and, if desired, separately reject empty-string/zero values).

        if default_interval and not isinstance(
            default_interval, (int, float, str)
        ):
            raise ValueError(
                "Invalid type: `default_interval` must be "
                + f"an int, float or str, not {type(default_interval)}"
            )

        # If no options are provided and default_interval is provided,
        if options is None:
            resolved_options = [default_interval] if default_interval else []
        else:
            resolved_options = options

        if not isinstance(resolved_options, list):
            raise ValueError(
                f"Invalid type: `options` must be a list, not {type(resolved_options)}"
            )

        # If has options and default_interval is provided,
        # check that default_interval is in options.
        if (
            default_interval
            and len(resolved_options) > 0
            and (default_interval not in resolved_options)
        ):