A streamlit custom component providing a searchbox with autocomplete.
pip install streamlit-searchboxCreate 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).
To customize the searchbox you can pass the following arguments:
search_function: Callable[[str], List[any]]Function that will be called on user input
key: str = "searchbox"Streamlit key for unique component identification.
placeholder: str = "Search ..."Placeholder for empty searches shown within the component.
label: str | None = NoneLabel shown above the component.
help: str | None = NoneShows a help icon with a popover. Only shown when the label is visible.
default: any = NoneDefault 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 = FalseUse the current searchterm as a default return value.
default_options: list[str] | None = NoneDefault options that will be shown when first clicking on the searchbox.
rerun_on_update: bool = TrueUse 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 = 150Delay 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 = 0DEPRECATED 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.
clear_on_submit: bool = FalseAutomatically 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 = NoneFunction that will be called when the combobox is reset.
submit_function: Callable[[Any], None] | None = NoneFunction that will be called when a new option is selected, with the selected option as argument.
style_overrides: dict | None = NoneSee section below for more details.
style_absolute: bool = FalseWill 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.
An example Streamlit app can be found here
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"
}
}
}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:
- Fork the repository.
- Create a new branch (
git checkout -b feature-branch). - Make your changes.
- Commit your changes (
git commit -am 'Add some feature'). - Push to the branch (
git push origin feature-branch). - Create a new Pull Request.
- @JoshElgar absolute positioning workaround
- @dopc bugfix for #15
- @Jumitti
st.reruncompatibility - @salmanrazzaq-94
st.fragmentsupport - @hoggatt
reset_function - @bram49
submit_function - @ytausch remove
testsfolder from distributions - @hansthen
helptooltip