st-combobox

• Installation
• Overview
• Usage
• Example

A streamlit custom component providing a combobox with autocomplete.

Installation

pip install st-combobox

Overview

Create a combobox component and pass a search_function that accepts a str searchterm. The combobox is triggered on user input and calls the search function for new options.`.

You can either pass a list of arguments, e.g.

import wikipedia
from st_combobox import st_combobox

# function with list of labels
def search_wikipedia(searchterm: str) -> List[any]:
    return wikipedia.search(searchterm) if searchterm else []


# pass search function to combobox
selected_value = st_combobox(
    search_wikipedia,
    key="wiki_combobox",
)

This example will call the Wikipedia Api to reload suggestions. The selected_value will be one of the items the search_wikipedia function returns, the suggestions shown in the UI components are a str representation. In case you want to provide custom text for suggestions, pass a Tuple.

def search(searchterm: str) -> List[Tuple[str, any]]:
    ...

Usage

To customize the combobox you can pass the following arguments:

selected_value = st_combobox(
    search_function: Callable[[str], List[any]],
    reset_function: Callable[[], None] = None,
    placeholder: str = "Search ...",
    label: str = None,
    default: any = None,
    clear_on_submit: bool = False,
    key: str = "combobox",
    rerun_on_update: bool = False,
    stop_on_update: bool = False,
    blank_search_value: str = None,
    return_only_on_submit: bool = False,
)

Explanations of the arguments

Function that will be called on user input

search_function: Callable[[str], List[any]]

Function that will be called when the combobox is reset.

reset_function: Callable[[], None] = None

Placeholder text when the combobox is blank.

placeholder: str = "Search ..."

Label shown above the component. If None, no label is shown.

label: str = None

Default return value in case nothing was submitted or the combobox cleared.

default: any = None

Automatically clear the input after selection.

clear_on_submit: bool = False

Streamlit key for unique component identification.

key: str = "combobox"

If true, will call st.rerun() on each search keystroke. If this is set to its default (False), the auto-complete results will always be one keystroke behind.

rerun_on_update: bool = False

If true (and rerun_on_update is false), will call st.stop() on each search keystroke.

stop_on_update: bool = False

If not None, will set the default search value when the box is initialized or reset.

blank_search_value: str = None

If true, will only return a non None value when the user selects an option. Otherwise, will keep returning the last value.

return_only_on_submit: bool = False

Example

An example Streamlit app can be found here.

Build

If any changes were made to the frontend, go to st_combobox/frontend and run npm run build (npm install --legacy-peer-deps if you don't have the packages on your machine). Then push the changes made to the frontend/build folder to the repo.

You may need to follow this help if you run into issues while building.

Now all you have to do is make a release and the github action will push to PyPi (make sure setup.py has a new verison).