Select

The Select widget displays a dropdown menu that lets users choose a single value from a list. It is ideal for filtering data, configuring options, or controlling the logic of your Mercury App.

Live Demo

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

🚀 Load interactive demo Hover to start

Usage

To create a Select widget, you only need to provide a list of choices. If no value is given, the first item from the list is selected automatically.

Basic Example

Code

import mercury as mr

fruit = mr.Select(
    label="Choose fruit",
    choices=["Apple", "Banana", "Cherry"]
)

To get the current selection:

fruit.value

Layout

Use position argument to change the widget placement. The default is position="sidebar" and slider is displayed in the left sidebar. Other available position are:

"inline" which displays Slider widget in the main view,
"bottom" which displays Slider widget in the bottom part of main view.

Code

sidebar_select = Select(
    label="Country",
    choices=["USA", "Poland", "Japan"],
    position="inline"
)

Select Props

label

type: string Text displayed above the dropdown. The deafult is "Select".

value

type: string The initial selected option. If omitted or invalid, it defaults to the first element of choices.

choices (required)

type: list[str] List of available options. If empty, the widget raises an exception.

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 dropdown is visible but cannot be changed. The default is False.

hidden

type: bool If True, the widget exists in the UI state but is not rendered. The default is False.

key

type: string

Unique identifier to distinguish widgets with identical arguments.

Notes

When no value is provided, the widget selects the first choice.
If the provided value is not in choices, it is replaced with the first element and a warning is shown.
The current selection is always available via .value.