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.

Option dictionaries use this shape:

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

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

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/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/*