streamlit-sortable-multiselect

A Streamlit custom component for searching, selecting, and reordering multiple string values.

Install

python -m pip install streamlit-sortable-multiselect

Upgrade an existing installation:

python -m pip install --upgrade streamlit-sortable-multiselect

For local development:

python -m pip install -e ".[dev]"

For frontend development:

cd streamlit_sortable_multiselect/frontend
npm install
npm run dev

Usage

import streamlit as st
from streamlit_sortable_multiselect import sortable_multiselect

selected = sortable_multiselect(
    "Favorite frameworks",
    options=[
        {"label": "Streamlit", "value": "streamlit", "icon_url": "https://streamlit.io/images/brand/streamlit-mark-color.png"},
        {"label": "FastAPI", "value": "fastapi", "icon_url": "https://fastapi.tiangolo.com/img/favicon.png"},
        {"label": "Django", "value": "django"},
        {"label": "Flask", "value": "flask"},
    ],
    default=["streamlit"],
    placeholder="Search frameworks...",
    show_move_buttons=True,
    show_numbers=True,
    base_color="#eef2ff",
    order_colors={1: "#fee2e2", 2: "#dcfce7"},
    max_selections=3,
    max_selections_placeholder="Choose up to 3 frameworks",
    empty_message="No frameworks selected",
    no_options_placeholder="All frameworks selected",
    selected_position="top",
    icon_size=24,
    options_max_height=260,
)

st.write(selected)

Settings

sortable_multiselect returns the selected option values as a list[str] in the current display order.

Argument	Type	Default	Description
label	str	required	Label displayed above the component.
options	Sequence[str | Mapping[str, Any]]	required	Available options. Each option can be a plain string, or a dictionary with label, value, and optional icon_url. Option values must be unique.
default	Sequence[str] | None	None	Initially selected values, in the initial order. Changing the values or their order replaces the current selection. Values must exist in options and must not contain duplicates.
default_revision	str | int | None	None	Change this value to reapply default when its values and order are unchanged.
placeholder	str	"Select..."	Placeholder shown in the search/add input when options are available.
disabled	bool	False	Disables searching, selecting, removing, dragging, and move buttons.
show_move_buttons	bool	True	Shows up/down buttons on selected items. Drag sorting remains available unless disabled=True.
show_numbers	bool	False	Shows 1-based position numbers before selected item labels.
base_color	str | Mapping[str, str] | None	None	Fallback color for every selected item. See Colors.
order_colors	Mapping[int, str | Mapping[str, str]] | None	None	Per-position colors. Positive keys count from the top (1 is first), negative keys count from the bottom (-1 is last), for example {1: "#fee2e2", -1: "#dcfce7"}.
value_colors	Mapping[str, str | Mapping[str, str]] | None	None	Per-value colors keyed by option value, for example {"python": "#3776ab"}. These follow an item as it is reordered.
color_palette	Sequence[str | Mapping[str, str]] | None	None	Colors cycled across selected positions. Position 1 uses the first entry and the palette repeats for longer selections.
color_priority	Sequence[str] | None	None	Ranking of the color sources "value", "option", "order", "palette", and "base". Omitted sources keep their default rank.
tooltip_color	str | Mapping[str, str] | None	None	Color of the tooltip shown for labels that do not fit. None uses the built-in dark tooltip. See Labels.
max_selections	int | None	None	Maximum number of selected items. None means no limit. Use 0 to prevent any selections.
single_select_display	bool	False	With max_selections=1, displays the selected item inside the search control and replaces it when another option is selected.
max_selections_placeholder	str	"Selection limit reached"	Placeholder shown when max_selections has been reached. This takes precedence over placeholder and no_options_placeholder, except in single-selection display mode.
empty_message	str	"No items selected"	Message shown where the selected list appears when no items are selected.
no_options_placeholder	str	"No more options"	Placeholder shown when every option is already selected and there are no more options to add.
selected_position	str	"bottom"	Position of the selected item list relative to the search/add input. Use "bottom" or "top".
icon_size	int	20	Icon display size in pixels for icon_url images. Images are displayed inside a square area while preserving their aspect ratio.
options_max_height	int	190	Maximum height in pixels for the available options dropdown.
suggestions_api_url	str | None	None	Absolute HTTP(S) endpoint used to fetch suggestions in the browser. None disables API suggestions.
suggestions_query_param	str	"q"	Query parameter name used to send the current search text.
suggestions_response_path	str	""	Dot-separated path to the suggestions array in the JSON response. Empty means the response root.
suggestions_label_path	str	"label"	Dot-separated path to each suggestion's display label.
suggestions_value_path	str	"value"	Dot-separated path to each suggestion's returned value.
suggestions_icon_url_path	str | None	"icon_url"	Optional dot-separated path to each suggestion's icon URL. None disables API icons.
suggestions_color_path	str | None	None	Optional dot-separated path to each suggestion's color. The value may be a CSS color string or a mapping of color fields. None disables API colors.
suggestions_headers	Mapping[str, str] | None	None	HTTP headers sent with suggestions requests. Header values are visible to browser users and must not contain secrets.
suggestions_min_chars	int	1	Minimum trimmed query length before requesting suggestions. Use 0 to allow an empty query.
suggestions_debounce_ms	int	300	Delay in milliseconds between the latest input and the API request.
suggestions_loading_message	str	"Loading suggestions..."	Message shown while an API request is in progress.
suggestions_error_message	str	"Failed to load suggestions"	Message shown when the request or response cannot be processed.
key	str | None	None	Optional Streamlit component key. Use this when rendering multiple sortable multiselects.

To reset a component to the same default after the user changes its selection, increment or otherwise change default_revision:

if "reset_revision" not in st.session_state:
    st.session_state.reset_revision = 0

if st.button("Reset languages"):
    st.session_state.reset_revision += 1

selected = sortable_multiselect(
    "Languages",
    options=["Python", "TypeScript", "Rust"],
    default=["Python"],
    default_revision=st.session_state.reset_revision,
)

Option dictionaries use this shape:

{
    "label": "Python",
    "value": "python",
    "icon_url": "https://www.python.org/static/favicon.ico",
    "color": "#3776ab",
}

icon_url and color may be omitted. The returned value is always the value, not the display label.

Colors

Anywhere a color is accepted, pass either a CSS color string or a mapping that sets any subset of background, text, and border:

"#fee2e2"
{"background": "#111827", "text": "#facc15", "border": "#f74c00"}

A string sets the background. When text is not set, the component picks black or white for readability against the resolved background.

Colors come from five sources. Each source contributes a color, and the highest ranked source that sets a field wins that field, so a value color that sets only text still inherits the background from base_color:

Source	Set with	Keyed by
value	value_colors	Option value. Follows the item as it is reordered.
option	color in an option dictionary, or suggestions_color_path	The option itself.
order	order_colors	Selected position. 1 is first, -1 is last.
palette	color_palette	Selected position, cycling through the palette.
base	base_color	Every selected item.

The default ranking is the table order. Reorder it with color_priority; sources you leave out keep their default rank, so color_priority=["order"] only promotes position colors above everything else.

When a positive and a negative order_colors key address the same slot, such as 1 and -3 in a three item list, the positive key wins. Every color must set at least one field: None and {} are rejected rather than ignored, so a mistyped color surfaces as an error instead of silently doing nothing.

selected = sortable_multiselect(
    "Podium",
    options=[
        {"label": "Python", "value": "python", "color": "#3776ab"},
        {"label": "Rust", "value": "rust"},
        {"label": "Go", "value": "go"},
    ],
    default=["python", "rust", "go"],
    # Gold, silver, and bronze by position, ranked above each option's own color.
    order_colors={
        1: {"background": "#fde68a", "border": "#f59e0b"},
        2: {"background": "#e5e7eb", "border": "#9ca3af"},
        -1: {"background": "#fed7aa", "border": "#ea580c"},
    },
    color_priority=["order"],
)

Options that resolve to a color show a small swatch in the options dropdown.

Because an option's value is its id, value_colors binds a color to an item rather than to a slot. examples/color_by_id.py puts both side by side: two lists holding the same items, one colored by position and one colored by id. Dragging an item in each shows position colors staying with the slot while id colors travel with the item.

Labels

Option labels in the dropdown are shown on one line and cut off with an ellipsis when they do not fit. Hovering a cut-off label shows the full text in a tooltip anchored to that label, and labels that fit are left without one. Selected item labels wrap onto multiple lines instead of being cut off, so they only get a tooltip if surrounding styles clip them.

The tooltip is drawn by the component rather than by the browser's native title, so it is styled with the rest of the component, appears after a short delay instead of about a second, and flips above or below the label to stay inside the component frame. It disappears as soon as the pointer leaves, the list scrolls, or the row it points at changes. Screen readers are unaffected either way: a clipped label is cut off visually but its full text is always in the DOM.

tooltip_color restyles it, using the same color form as everything above. A string sets the background and the text follows for contrast; a mapping may also set text and border. Because the component renders inside an iframe, this argument is the only way to change the tooltip: styles from the surrounding app cannot reach it.

tooltip_color="#1e3a8a"                                              # white text follows
tooltip_color={"background": "#ffffff", "text": "#111827", "border": "#d1d5db"}

A light tooltip needs a border to separate it from the content behind it. The arrow picks up both the background and the border, so it stays attached either way.

examples/tooltip_labels.py shows the same options in a narrow list and a wide one, so the conditional behavior is visible side by side.

Single Selection Display

Set single_select_display=True together with max_selections=1 to keep the selected item inside the search control. The external selected-item list is not rendered in this mode. The item keeps its label, icon, resolved colors, optional number, and truncated label tooltip. Because no external selected list is rendered, selected_position, empty_message, and show_move_buttons do not affect this mode.

selected = sortable_multiselect(
    "Primary language",
    options=[
        {"label": "Python", "value": "python", "icon_url": "https://www.python.org/static/favicon.ico"},
        {"label": "TypeScript", "value": "typescript"},
        {"label": "Rust", "value": "rust"},
    ],
    default=["python"],
    max_selections=1,
    single_select_display=True,
)

The input remains available after a selection. Opening the choices and selecting a new option replaces the current value instead of adding another one. Use the remove button inside the selected item to clear it. single_select_display=True without max_selections=1 raises ValueError.

API Suggestions

Set suggestions_api_url to request suggestions as the user types. Static options that match the query are shown first, followed by API results. Duplicate value entries prefer the static option.

selected = sortable_multiselect(
    "Repositories",
    options=[{"label": "Streamlit", "value": "streamlit/streamlit"}],
    suggestions_api_url="https://api.example.com/repositories",
    suggestions_query_param="query",
    suggestions_response_path="data.items",
    suggestions_label_path="name",
    suggestions_value_path="full_name",
    suggestions_icon_url_path="owner.avatar_url",
    suggestions_headers={"X-Public-Client": "streamlit-app"},
    suggestions_min_chars=2,
    suggestions_debounce_ms=300,
    suggestions_loading_message="Searching repositories...",
    suggestions_error_message="Repository search is unavailable",
)

The example above accepts a response such as:

{
  "data": {
    "items": [
      {
        "name": "streamlit-sortable-multiselect",
        "full_name": "example/streamlit-sortable-multiselect",
        "owner": {
          "avatar_url": "https://example.com/avatar.png"
        }
      }
    ]
  }
}

Requests are made directly from the component iframe, so the endpoint must allow browser requests with CORS. Values in suggestions_headers are exposed to browser users. Do not pass API secrets, private bearer tokens, or other credentials. Use a server-side proxy when authentication must remain private.

The component sends a GET request after the trimmed input reaches suggestions_min_chars and remains unchanged for suggestions_debounce_ms. Changing the input cancels the previous in-flight request. Set options=[] to use only API results. Selected API values remain selected when a later query returns different suggestions.

Build the frontend before packaging or using release mode:

cd streamlit_sortable_multiselect/frontend
npm run build

Run the example app:

streamlit run examples/basic.py
streamlit run examples/color_by_id.py
streamlit run examples/tooltip_labels.py
streamlit run examples/api_suggestions.py

api_suggestions.py starts a CORS-enabled sample API on a local random port, so it can be tried without a separate API process. This embedded server is intended for local development; use a separately deployed HTTPS API in remote deployments. The Streamlit page displays the address and port selected for the API. Test the endpoint from the same machine with:

curl "http://127.0.0.1:<displayed-port>/suggest?q=py"

Pass a fixed API port after -- when needed:

streamlit run examples/api_suggestions.py -- --api-port 8765

The embedded API binds to 127.0.0.1. Because suggestions are fetched by the browser, it works only when the browser and Streamlit run on the same machine. For Docker, another computer, or a hosted Streamlit app, configure suggestions_api_url with a browser-accessible HTTPS endpoint instead.

Release

Build and check the distribution files:

cd streamlit_sortable_multiselect/frontend
npm install
npm run build
cd ../..
python -m pip install -e ".[dev]"
python -m build
python -m twine check dist/*

Upload to PyPI with an API token:

python -m twine upload dist/*