MultiSelect

The MultiSelect widget displays a dropdown menu that allows users to choose multiple values from a list. It is well suited for filtering data, selecting multiple categories, or controlling more complex logic in your Mercury App.

Live Demo

You can try the MultiSelect widget directly in this interactive example:

🚀 Load interactive demo Hover to start

Usage

To create a MultiSelect widget, you must provide a non-empty list of choices. You may optionally provide a list of default selected values using the value argument.

If no value is provided (or if it is None), the widget selects the first element from choices by default.

Basic Example

Create MultiSelect widget:

fruits = MultiSelect(
    label="Choose fruits",
    choices=["Apple", "Banana", "Cherry"]
)

To get the current selection, use value attribute:

fruits.value

In this case, the initial value will be:

["Apple"]

Default Values

You can specify one or more default selections using the value argument.

Code

fruits = mr.MultiSelect(
    label="Choose fruits",
    choices=["Apple", "Banana", "Cherry"],
    value=["Banana", "Cherry"]
)

If any values provided in value are not present in choices, they are automatically removed and a warning is shown. If all provided values are invalid, the widget falls back to selecting the first available choice during initialization.

Layout

Use the position argument to control where the widget is displayed. The default is position="sidebar", which renders the widget in the left sidebar.

Other available values are:

"inline" — displays the widget in the main notebook output,
"bottom" — displays the widget after all notebook cells.

Code

countries = MultiSelect(
    label="Countries",
    choices=["USA", "Poland", "Japan"],
    position="inline"
)

MultiSelect Props

label

type: string Text displayed above the widget. The default is "Select".

value

type: list[str] | None

Initial list of selected values.

If None or omitted, the first element from choices is selected.
Invalid values are removed during initialization.
After user interaction, the value may become an empty list.

The widget value is never None at runtime.

choices (required)

type: list[str]

List of available options. Must be non-empty, otherwise an exception is raised.

placeholder

type: string

Text displayed when no values are selected. This is visible, for example, after the user clears all selections.

The default is an empty string.

position

type: "sidebar" | "inline" | "bottom"

Controls where the widget is rendered:

sidebar — in the sidebar (default)
inline — directly in the notebook cell output
bottom — after all notebook cells

disabled

type: bool

If True, the widget is visible but cannot be interacted with. The default is False.

hidden

type: bool

If True, the widget exists in the UI state but is not rendered.

This is useful for internal state management. The default is False.

key

type: string

Unique identifier used to distinguish widgets with identical arguments.

Notes

The widget value is always a list of strings.
During initialization, at least one value is selected by default.
During user interaction, the value may become an empty list (for example when the user clears all selections).
Invalid values are removed automatically.
The current selection is always available via .value.