streamlit-sortable-multiselect

A Streamlit custom component for searching, selecting, and reordering options, dates, months, and date/month ranges. Selected items can be reordered by dragging or using move buttons, and are returned as an ordered list[str].

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

The default input_mode="options" provides searchable options. For calendar inputs, see Calendar Input, including date ranges, single months, selection bounds, and Japanese labels and messages.

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 selected values as a list[str] in the current display order. Calendar values use the formats in Returned Values.

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:

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.

In calendar modes, the selected item is displayed inside the calendar control. Adding another calendar value replaces it. A date range counts as one selected item.

Calendar Input

Input Modes

input_mode selects the input method for the whole component:

Use input_mode="date_month" to add date ranges and single months to one sortable list. One switch selects Date (range) or Month (single). Date (range) shows Start and End inputs; Month (single) shows one month input. Press Add to append the selection. A range is one item, not an expanded sequence. Use "date" or "month" for a fixed precision with a separate Single/Range switch.

import streamlit as st
from streamlit_sortable_multiselect import sortable_multiselect

selected = sortable_multiselect(
    "Reporting periods",
    input_mode="date_month",
    min_value="2026-01-01",
    max_value="2027-12-31",
    max_range_days=31,
    default=["2026-10-01/2026-10-24", "2026-11"],
    show_numbers=True,
    key="reporting_periods",
)
st.write("Selected order:", selected)

Mixed mode initially shows the date-range inputs. Switching to Month (single) clears unfinished inputs and keeps items already added to the sortable list.

Calendar Labels

Override calendar_labels to display Japanese or another language. The settings apply to switch text, the Add button, field labels, accessibility group names, and validation messages. They do not change returned values. Supported keys and defaults are:

Only specify the labels you want to override. Unknown keys, non-string values, and empty or whitespace-only labels raise an error. In range_too_long, every {max_range_days} placeholder is replaced with the configured limit; a message without the placeholder is also allowed. Native calendar localization follows the browser and operating system. Set empty_message for the empty selected list and max_selections_placeholder for the selection-count limit message.

Japanese Example

import streamlit as st
from streamlit_sortable_multiselect import sortable_multiselect

selected = sortable_multiselect(
    "Reporting periods",
    input_mode="date_month",
    min_value="2026-01-01",
    max_value="2027-12-31",
    max_range_days=31,
    default=["2026-10-01/2026-10-24", "2026-11", "2027-01"],
    show_numbers=True,
    max_selections=8,
    calendar_labels={
        "date_range": "日付（範囲）",
        "month_single": "年月（単一）",
        "single": "単一",
        "range": "範囲",
        "add": "追加",
        "start": "開始日",
        "end": "終了日",
        "date": "日付",
        "month": "年月",
        "calendar_input": "入力方法",
        "selection_kind": "選択方法",
        "invalid_value": "選択範囲を確認してください。",
        "duplicate_value": "この項目は選択済みです。",
        "incomplete_selection": "追加する値をすべて入力してください。",
        "range_too_long": "{max_range_days}日以内で指定してください。",
    },
    empty_message="期間が選択されていません。",
    max_selections_placeholder="選択数の上限に達しました。",
    key="periods",
)
st.write(selected)

Returned Values

Across the calendar modes, the returned list[str] retains the selected order and identifies precision by format:

Ranges include both endpoints, require the same precision at each end, and must start on or before their end. Overlapping ranges are allowed; identical items cannot be added twice. Dates and months may coexist in mixed mode. Switching precision clears the unfinished input and preserves added items.

Bounds and Range Length

Bounds are optional. A YYYY-MM lower bound expands to the first day of that month and an upper bound to its last day. Month selections compare by month: min_value="2026-01-15" still permits the month "2026-01", while date selections must be on or after January 15. Changing bounds or input mode removes selected items that are no longer valid.

Set max_range_days=31 to allow at most 31 days in each date range. Both endpoints count: January 1 through January 31 is 31 days; January 1 through February 1 is 32 days and cannot be added. max_range_days=1 allows only same-day date ranges. The end picker uses the earlier of max_value and the start date plus max_range_days - 1 days. Invalid defaults and option metadata values raise an error, and reducing the limit removes date ranges that exceed it. This limit does not restrict single months or month ranges; min_value and max_value still apply. It is available only in calendar modes.

Use a datetime.date object or an ISO string for bounds. datetime.datetime objects are not accepted. Calendar defaults remain strings, such as "2026-10" and "2026-10-01/2026-10-31".

Shared Settings

Existing ordering, numbering, colors, selection limits, disabled states, selected_position, default_revision, and inline single selection apply to calendar items. options is optional and can supply metadata for known calendar values; it does not restrict which valid values the picker accepts. API suggestions are available only in options mode. Search placeholders and dropdown height do not affect calendar inputs; max_selections_placeholder appears as a status message when the limit is reached.

Browser Support

Date and month inputs use the browser's native picker, whose presentation and language depend on the browser and operating system. Browsers without a native month picker can accept YYYY-MM as text; the same validation applies. Calendar values are strings without timezone conversion. See examples/calendar_input.py for mixed, date-only, month-only, and form examples, including Japanese messages.

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.

Examples

See examples/README.md for a description of each example. 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/calendar_input.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.

Troubleshooting

If a new argument such as calendar_labels or max_range_days raises TypeError: sortable_multiselect() got an unexpected keyword argument ..., check the package path and function signature in the Python environment used to run Streamlit:

python -c 'import inspect; import streamlit_sortable_multiselect as sms; print(sms.__file__); print(inspect.signature(sms.sortable_multiselect))'

For repository development, install the local package in that environment with python -m pip install -e ".[dev]". If the signature includes the argument but an existing Streamlit process still reports it as unexpected, stop that process and restart it to load the updated Python module:

python -m streamlit run examples/calendar_input.py

After rebuilding frontend assets, reload the app page to pick up the updated UI.

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