Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 38 ยท Input Widgets

Choice Widgets

Let users choose with Streamlit selectbox, radio, multiselect, slider, select_slider, pills and segmented_control. Learn return values, defaults, format_func and filtering data.

Most dashboards are a set of choices followed by a filtered view: pick a region, pick a date range, pick the columns. Streamlit has a widget for each kind of choice, and the choice is almost always a Python value (a string, a list, a number or a tuple) that you use directly to filter a DataFrame.

The Streamlit snippets are real and read-only, with the result described. The filtering logic runs in your browser with pandas, so you can see the data the widgets would select.

Pick one: selectbox, radio, pills

Python
import streamlit as st

drink = st.selectbox("Drink", ["Tea", "Coffee", "Juice"])
size = st.radio("Size", ["Small", "Medium", "Large"], index=1, horizontal=True)
mood = st.pills("Mood", ["Happy", "Tired", "Curious"])
st.write(drink, size, mood)

The page shows a drop-down with "Tea" selected, a row of three round radio buttons with "Medium" selected, and a row of clickable pill buttons with none selected. The last line reads "Tea Medium None". The values are:

Widget Returns Good for
selectbox The chosen option Many options (searchable by typing)
radio The chosen option 2 to 6 options you want visible at once
segmented_control The chosen option or None 2 to 5 short options in a compact bar
pills The chosen option (or list with selection_mode="multi") Tags and short choices

Details worth knowing:

  • selectbox(..., index=None, placeholder="Choose a drink") starts with nothing selected and returns None until the user chooses. The default is the first option.
  • radio always has one option selected unless you pass index=None.
  • Options can be any list of objects: numbers, strings, even tuples. The widget returns the object itself, not its text.
  • format_func= changes how options are displayed without changing what is returned (next section).
  • captions=["...", "...", "..."] on a radio adds small descriptions under each option.

Showing nice labels with format_func

Suppose your data uses codes ("NO", "PE") but users should see names. Keep the code as the option and format for display:

Python
countries = {"NO": "Norway", "PE": "Peru", "IN": "India"}
code = st.selectbox("Country", list(countries), format_func=lambda c: countries[c])
st.write("Selected code:", code)

The drop-down shows "Norway", "Peru", "India", while code is "NO" when Norway is chosen, so the page says "Selected code: NO". You are free to use that code in the DataFrame filter.

Python Stand-in: format_func keeps the real value

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Pick several: multiselect

Python
picked = st.multiselect(
    "Regions",
    options=["North", "South", "East", "West"],
    default=["North", "East"],
    max_selections=3,
)
st.write(picked)

The page shows a box holding two removable chips, "North" and "East", with a drop-down list for adding more; at most three can be chosen. It returns a list of the chosen options (empty when none), in the order the user selected them, so the page text is ['North', 'East']. An empty list is a common edge case: decide whether "no selection" means "show nothing" or "show everything".

Numbers on a scale: slider and select_slider

Python
import datetime as dt
import streamlit as st

age = st.slider("Age", 0, 100, 25)                         # one handle, int
low, high = st.slider("Price range", 0.0, 100.0, (20.0, 60.0))   # two handles
day = st.slider("Day", dt.date(2025, 1, 1), dt.date(2025, 12, 31), dt.date(2025, 6, 1))
level = st.select_slider("Quality", options=["Low", "Medium", "High"], value="Medium")

The first slider returns an integer. The second has two handles and returns a tuple (low, high), which you can unpack right away because the default (20.0, 60.0) is a tuple. The third works on dates, datetime times and datetimes too. select_slider slides over a list of labels, so it suits ordered words like sizes and ratings, and returns the chosen label (or a tuple of labels for a range).

The rule for the type is the same as number_input: integer arguments give integers, float arguments give floats, and you must not mix them.

Sliders rerun the script while you drag (after a short pause on release). On a heavy page that can mean many runs; for expensive work, put widgets in a form (see Forms and Callbacks) or cache the work.

Using the choices: filter a DataFrame

The widgets are only inputs. The pandas filter turns them into a view. Try this runnable version, with fixed values standing in for the widgets:

Python Filter a DataFrame with widget values

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The isin and between methods are the natural partners of multiselect and a two-handle slider. Always handle the "All" case explicitly, as above, rather than adding it to the data.

Dynamic options

Options often come from the data itself:

Python
regions = sorted(df["region"].unique())
chosen = st.multiselect("Regions", regions, default=regions)

Because the options are computed on each run, if they change between runs the widget is considered new and loses its selection. When options change often, give the widget a key and keep the values consistent, or store the selection in session state.

Also remember cascades: a second selectbox whose options depend on the first one just reads the first's return value and filters the data. The script order from top to bottom makes this easy:

Python Dependent drop-downs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Choosing the right widget

One value or many?

One option selectbox, radio, pills
Many options multiselect
A number slider
Ordered labels select_slider
1 / 2

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does st.multiselect return?

    It returns a list, which is empty when nothing is selected.
  2. 2. How do you make a selectbox start with no option chosen?

    index=None leaves it empty; it returns None until the user picks something.
  3. 3. A slider is created with the default (20.0, 60.0). What does it return?

    A tuple default makes a range slider with two handles that returns a tuple.
  4. 4. What does format_func change?

    format_func only affects the displayed label; the widget still returns the original option.

Summary

  • selectbox, radio, segmented_control and pills choose one option; multiselect returns a list.
  • slider returns a number, date or a tuple for ranges; select_slider slides over labels.
  • format_func shows friendly labels while returning real values; index=None starts empty.
  • Turn widget values into pandas filters with isin, between and boolean masks.

Next: Date, File and Media Input