| Function signature[source] | |
|---|---|
st.selectbox(label, options, index=0, format_func=special_internal_function, key=None, help=None, on_change=None, args=None, kwargs=None, *, placeholder="Choose an option", disabled=False, label_visibility="visible") | |
| Parameters | |
label (str) | A short label explaining to the user what this select widget is for. The label can optionally contain GitHub-flavored Markdown of the following types: Bold, Italics, Strikethroughs, Inline Code, and Links. Unsupported Markdown elements are unwrapped so only their children (text contents) render. Display unsupported elements as literal characters by backslash-escaping them. E.g., "1\. Not an ordered list". See the body parameter of st.markdown for additional, supported Markdown directives. For accessibility reasons, you should never set an empty label (label="") but hide it with label_visibility if needed. In the future, we may disallow empty labels by raising an exception. |
options (Iterable) | Labels for the select options in an Iterable. This can be a list, set, or anything supported by st.dataframe. If options is dataframe-like, the first column will be used. Each label will be cast to str internally by default. |
index (int) | The index of the preselected option on first render. If None, will initialize empty and return None until the user selects an option. Defaults to 0 (the first option). |
format_func (function) | Function to modify the display of the labels. It receives the option as an argument and its output will be cast to str. |
key (str or int) | An optional string or integer to use as the unique key for the widget. If this is omitted, a key will be generated for the widget based on its content. Multiple widgets of the same type may not share the same key. |
help (str) | An optional tooltip that gets displayed next to the selectbox. |
on_change (callable) | An optional callback invoked when this selectbox's value changes. |
args (tuple) | An optional tuple of args to pass to the callback. |
kwargs (dict) | An optional dict of kwargs to pass to the callback. |
placeholder (str) | A string to display when no options are selected. Defaults to "Choose an option". |
disabled (bool) | An optional boolean, which disables the selectbox if set to True. The default is False. |
label_visibility ("visible", "hidden", or "collapsed") | The visibility of the label. If "hidden", the label doesn't show but there is still empty space for it above the widget (equivalent to label=""). If "collapsed", both the label and the space are removed. Default is "visible". |
| Returns | |
(any) | The selected option or None if no option is selected. |
Example
import streamlit as st option = st.selectbox( "How would you like to be contacted?", ("Email", "Home phone", "Mobile phone"), ) st.write("You selected:", option)To initialize an empty selectbox, use None as the index value:
import streamlit as st option = st.selectbox( "How would you like to be contacted?", ("Email", "Home phone", "Mobile phone"), index=None, placeholder="Select contact method...", ) st.write("You selected:", option)
Select widgets can customize how to hide their labels with the label_visibility parameter. If "hidden", the label doesn’t show but there is still empty space for it above the widget (equivalent to label=""). If "collapsed", both the label and the space are removed. Default is "visible". Select widgets can also be disabled with the disabled parameter:
import streamlit as st
# Store the initial value of widgets in session state
if "visibility" not in st.session_state:
st.session_state.visibility = "visible"
st.session_state.disabled = False
col1, col2 = st.columns(2)
with col1:
st.checkbox("Disable selectbox widget", key="disabled")
st.radio(
"Set selectbox label visibility 👉",
key="visibility",
options=["visible", "hidden", "collapsed"],
)
with col2:
option = st.selectbox(
"How would you like to be contacted?",
("Email", "Home phone", "Mobile phone"),
label_visibility=st.session_state.visibility,
disabled=st.session_state.disabled,
)
Still have questions?
Our forums are full of helpful information and Streamlit experts.