streamlit-searchbox

• streamlit-searchbox
  • Installation
  • Overview
  • Parameters
    • Required
    • Visual
    • Defaults
    • Reruns
    • Transitions
    • Custom Styles
  • Example
  • Styling
  • Contributions
    • Contributors

A streamlit custom component providing a searchbox with autocomplete.

Installation

pip install streamlit-searchbox

Overview

Create a searchbox component and pass a search_function that accepts a str searchterm. The searchbox is triggered on user input, calls the search function for new options and redraws the page via st.experimental_rerun().

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

import streamlit as st
import wikipedia

from streamlit_searchbox import st_searchbox


def search_wikipedia(searchterm: str) -> list:
    # search wikipedia for the searchterm
    return wikipedia.search(searchterm) if searchterm else []


# pass search function and other options as needed
selected_value = st_searchbox(
    search_wikipedia,
    placeholder="Search Wikipedia... ",
    key="my_key",
)

st.write(f"Selected value: {selected_value}")

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 or retain more information from the search, you can also return a tuple from your search function.

def search(searchterm: str) -> list[tuple[str, dict]]:
    return [
        (
            result["title"],  # display in the search box itself
            result,  # returned on item selection
        )
        for result in requests.get(f"http://some.endpoint?term={searchterm}").json()
    ]

selected_value = st_searchbox(search, ...)
st.json(selected_value)

You can also pass additional keyword arguments to a search function in case you need more context by adding them to st_searchbox(search, a=1, b=2).

Parameters

To customize the searchbox you can pass the following arguments:

Required

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

Function that will be called on user input

key: str = "searchbox"

Streamlit key for unique component identification.

Visual

placeholder: str = "Search ..."

Placeholder for empty searches shown within the component.

label: str | None = None

Label shown above the component.

help: str | None = None

Shows a help icon with a popover. Only shown when the label is visible.

Defaults

default: any = None

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

default_searchterm: str = ''

Default searchterm value when the searchbox is initialized.

default_use_searchterm: bool = False

Use the current searchterm as a default return value.

default_options: list[str] | None = None

Default options that will be shown when first clicking on the searchbox.

Reruns

rerun_on_update: bool = True

Use st.experimental_rerun() to reload the app after user input and load new search suggestions. Disabling leads to delay in showing the proper search results.

rerun_scope: Literal["app", "fragment"] = "app",

If the rerun should affect the whole app or just the fragment.

debounce: int = 150

Delay executing the callback from the react component by x milliseconds to avoid too many / redundant requests, i.e. during fast typing.

min_execution_time: int = 0

DEPRECATED Delay execution after the search function finished to reach a minimum amount of x milliseconds. This can be used to avoid fast consecutive reruns, which can cause resets of the component in some streamlit versions >=1.35 and <1.39.

Transitions

clear_on_submit: bool = False

Automatically clear the input after selection.

edit_after_submit: Literal["disabled", "current", "option", "concat"] = "disabled"

Specify behavior for search query after an option is selected. By setting edit_after_submit to option you can use the searchbox similar to an autocomplete.

reset_function: Callable[[], None] | None = None

Function that will be called when the combobox is reset.

submit_function: Callable[[Any], None] | None = None

Function that will be called when a new option is selected, with the selected option as argument.

Custom Styles

style_overrides: dict | None = None

See section below for more details.

style_absolute: bool = False

Will position the searchbox as an absolute element. NOTE: this will affect all searchbox instances and should either be set for all boxes or none. See #46 for initial workaround by @JoshElgar.

Example

An example Streamlit app can be found here

Styling

To further customize the styling of the searchbox, you can override the default styling by passing style_overrides which will be directly applied in the react components. See below for an example, for more information on the available attributes, please see styling.tsx as well as the react-select documentation.

{
   // change the clear icon
   "clear":{
      "width":20,
      "height":20,
      // also available: circle-unfilled, circle-filled
      "icon":"cross",
      // also available: never, after-submit
      "clearable":"always"
   },
   // change the dropdown icon
   "dropdown":{
      "rotate":true,
      "width":30,
      "height":30,
      "fill":"red"
   },
   // styling for the searchbox itself, mostly passed to react-select
   "searchbox":{
      "menuList":{
         "backgroundColor":"transparent"
      },
      "singleValue":{
         "color":"red"
      },
      "option":{
         "color":"blue",
         "backgroundColor":"yellow",
         // highlight matching text
         "highlightColor":"green"
      }
   }
}

Contributions

We welcome contributions from everyone. Here are a few ways you can help:

• Reporting bugs: If you find a bug, please report it by opening an issue.
• Suggesting enhancements: If you have ideas on how to improve the project, please share them by opening an issue.
• Pull requests: If you want to contribute directly to the code base, please make a pull request. Here's how you can do so:
  1. Fork the repository.
  2. Create a new branch (git checkout -b feature-branch).
  3. Make your changes.
  4. Commit your changes (git commit -am 'Add some feature').
  5. Push to the branch (git push origin feature-branch).
  6. Create a new Pull Request.

Contributors

• @JoshElgar absolute positioning workaround
• @dopc bugfix for #15
• @Jumitti st.rerun compatibility
• @salmanrazzaq-94 st.fragment support
• @hoggatt reset_function
• @bram49 submit_function
• @ytausch remove tests folder from distributions
• @hansthen help tooltip