Skip to content

πŸ”’Β Β Button Selector

Submitted by Zhijia Liu

Summary

A button selector that can be used to select an item from a list of options.

Functions

button_selector

Create a button selector for choosing an item from a list of options.

This function creates a grid of buttons representing the items in the provided list. The selected button is highlighted, and the index of the selected item is returned.

Parameters:

Name Type Description Default
options Sequence[str]

A list of strings representing the selectable options.

 required
index int

The index of the default selected item. Defaults to 0.

 0
spec int

The number of columns in the button grid. Defaults to 4.

 4
key str

A unique key for the button selector. Used for maintaining state.

 'button_selector'
label str

A label for the button selector. Defaults to None.

 None

Returns:

Name Type Description
int int

The index of the currently selected item in the options.
Note

This function uses Streamlit's session state to maintain the selected item across reruns of the app.

Source code in src/streamlit_extras/button_selector/__init__.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
@extra
def button_selector(
    options: Sequence[str],
    index: int = 0,
    spec: int = 4,
    key: str = "button_selector",
    label: Optional[str] = None,
) -> int:
    """
    Create a button selector for choosing an item from a list of options.

    This function creates a grid of buttons representing the items in the provided list.
    The selected button is highlighted, and the index of the selected item is returned.

    Args:
        options (Sequence[str]): A list of strings representing the selectable options.
        index (int, optional): The index of the default selected item. Defaults to 0.
        spec (int, optional): The number of columns in the button grid. Defaults to 4.
        key (str, optional): A unique key for the button selector. Used for maintaining state.
        label (str, optional): A label for the button selector. Defaults to None.

    Returns:
        int: The index of the currently selected item in the options.

    Note:
        This function uses Streamlit's session state to maintain the selected item
        across reruns of the app.
    """

    def incre_str(s: str) -> str:
        return re.sub(
            r"(?:(\d+))?$",
            lambda x: "_0" if x.group(1) is None else str(int(x.group(1)) + 1),
            s,
        )

    def get_selected_index() -> int:
        if key not in st.session_state:
            st.session_state[key] = index
        selected_index = st.session_state.get(key)
        if selected_index not in range(len(options)):
            selected_index = index
        return selected_index

    def set_selected(selected_index: int, button_key: str):
        st.session_state[key] = selected_index
        # refresh the button's state
        st.session_state[button_key] = incre_str(st.session_state[button_key])

    if label is not None:
        st.caption(f":gray[{label}]")

    num = len(options)
    grid_numbers = [spec] * (num // spec + 1)
    g = grid(*grid_numbers)

    for id, name in enumerate(options):
        t = "primary" if id == get_selected_index() else "secondary"
        button_key = f"{key}_{name}"
        st.session_state[button_key] = f"{button_key}_value_0"
        g.button(
            name,
            key=st.session_state[button_key],
            use_container_width=True,
            type=t,
            on_click=set_selected,
            args=(id, button_key),
        )

    return get_selected_index()

Import:

from streamlit_extras.button_selector import button_selector # (1)!
  1. You should add this to the top of your .py file πŸ› 

Examples

example

def example():
    month_list = [
        "Jan",
        "Feb",
        "Mar",
        "Apr",
        "May",
        "Jun",
        "Jul",
        "Aug",
        "Sep",
        "Oct",
        "Nov",
        "Dec",
    ]
    selected_index = button_selector(
        month_list,
        index=0,
        spec=4,
        key="button_selector_example_month_selector",
        label="Month Selector",
    )
    st.write(f"Selected month: {month_list[selected_index]}")
Output (beta)