Skip to content

selector

A control that allows for selecting items from a list of choices.

Each item is represented by a string, an image or both.

The selector can let the user select multiple items.

A filtering feature is available to display only a subset of the items.

You can use an arbitrary type for all the items (see the example).

Properties

Name Type Default Description
value(★) Any
dynamic

Bound to the selection value.

label str None

The label associated with the selector when in dropdown mode.

mode str

Define the way the selector is displayed:

  • "radio": as a list of radio buttons
  • "check": as a list of check boxes
  • any other value: a plain list.

dropdown bool False

If True, the list of items is shown in a dropdown menu.

You cannot use the filter in that situation.

multiple bool False

If True, the user can select multiple items.

filter bool False

If True, this control is combined with a filter input area.

width Union[str,int] "360px"

The width of this selector, in CSS units.

height Union[str,int]

The height of this selector, in CSS units.

lov dict[str, Any]

The list of values. See the section on List of Values for more details.

adapter Union[str, Callable] lambda x: str(x)

A function or the name of the function that transforms an element of lov into a tuple(id:str, label:Union[str,Icon]).
The default value is a function that returns the string representation of the lov element.

type str Type name of the first lov element

This property is required if lov contains a non-specific type of data (e.g., a dictionary).
Then:

  • value must be of that type
  • lov must be an iterable containing elements of this type
  • The function set to adapter will receive an object of this type.

The default value is the type of the first element in lov.

value_by_id bool False

If False, the selection value (in value) is the selected element in lov. If set to True, then value is set to the id of the selected element in lov.

on_change Union[str, Callable]

A function or the name of a function that is triggered when the value is updated.
This function is invoked with the following parameters:

  • state (State): the state instance.
  • var_name (str): the variable name.
  • value (Any): the new value.

propagate bool App config

Allows the control's main value to be automatically propagated.
The default value is defined at the application configuration level by the propagate configuration option.
If True, any change to the control's value is immediately reflected in the bound application variable.

active bool
dynamic
True

Indicates if this component is active.
An inactive component allows no user interaction.

id str

The identifier that is assigned to the rendered HTML component.

properties dict[str, Any]

Bound to a dictionary that contains additional properties for this element.

class_name str
dynamic

The list of CSS class names that are associated with the generated HTML Element.
These class names are added to the default taipy-selector class name.

hover_text str
dynamic

The information that is displayed when the user hovers over this element.

(★)value is the default property for this visual element.

Details

By default, the selector control displays elements as a series of text items:

A selector with several items

The user can select an item, which is then highlighted within the control.

If the multiple property is set to True, the selector displays as a series of toggle buttons that users can both select and deselect:

Multiple selection

Multiple items can be selected, and the value property is set to an array containing the selected items.

Display modes

The mode property controls how the selector is displayed and can be set to either "check" or "radio".

  • When mode is set to "check", the control appears as a list of toggle buttons.

    "check" mode
    The multiple property is automatically set to True.

  • When the mode is set to "radio", the control displays as a list of radio buttons.

    "radio" mode
    The multiple property is automatically set to False

Usage

Display a list of string

To create a selector control for a list of strings, you can use a semicolon-separated string, which is assigned to the lov (List of Values) property.

Below is a control definition that demonstrates this:

Definition

<|{value}|selector|lov=Item 1;Item 2;Item 3|>
<taipy:selector lov="Item 1;Item 2;Item 3">{value}</taipy:selector>
import taipy.gui.builder as tgb
...
tgb.selector("{value}", lov="Item 1;Item 2;Item 3")

The value property of the selector is bound to the value variable. This variable should be set to one of the items in the list, ensuring that the selected value corresponds to one of the provided list items..
For example:

value="Item 2"

When the user changes the selection, value reflects the new selection in the user's state.

With these settings, the control appears as follows:

Simple selector

Display as a dropdown

To display the selector as a drop-down menu, set the dropdown property to True:

Definition

<|{value}|selector|lov=Item 1;Item 2;Item 3|dropdown|>
<taipy:selector lov="Item 1;Item 2;Item 3" dropdown>{value}</taipy:selector>
import taipy.gui.builder as tgb
...
tgb.selector("{value}", lov="Item 1;Item 2;Item 3", dropdown=True)

If value is set as in the previous example, the control will appear as shown below:

Selector with a drop-down button

Clicking the drop-down button reveals the full list:

Selector with the drop-down list

Display with filter

You can add a filter input field to display only the strings that match the filter value.

For example, suppose you want to create a selector that allows users to select from a list of all Python built-in functions. You would use the following code:

import builtins
import inspect
...
builtin_python_functions = [
    func
    for func in dir(builtins)
    if callable(getattr(builtins, func)) and not inspect.isclass(getattr(builtins, func)) and not func.startswith("_")
]
selection = builtin_python_functions[0]

This code stores the list of all Python built-in functions (excluding those that start with "_") in the variable builtin_python_functions. The selection variable is set to the first element of this list.

Here is how to define a selector control that displays this list:

Definition

<|{selection}|selector|lov={builtin_python_functions}|filter|multiple|>
<taipy:selector lov="{builtin_python_functions}" filter multiple>{selection}</taipy:selector>
import taipy.gui.builder as tgb
...
tgb.selector("{selection}", lov="{builtin_python_functions}", filter=True, multiple=True)

In this selector, multi-selection is enabled with the multiple property set to True.

Here is how the control is displayed:

Selector with a long list

An input field (labeled "Search field") appears at the top of the control.
Note that because the list of items is very long, is not fully represented here.

If the user enters the string "ex" in the search field, only the items containing that string are displayed:

Filtered items

Display labels and icons

You can use the lov property to display labels or icons in the selector control.
Each element of the list-of-values (lov) should be a tuple where:

  • The first element is a unique identifier, used in the value property;
  • The second element is the display content, which can be text or an icon.

Let us create a list-of-values (lov) that we want to represent in the selector:

lov = [
    ("id1", "Framework X"),
    ("id2", Icon("https://docs.taipy.io/en/latest/assets/images/favicon.png", "Taipy")),
    ("id3", "Framework Y"),
]

The lov variable is set to an array of three tuples.
The second one ("id2") represents an icon, using the URL to the image along with the label "Taipy."

The definition below uses the lov variable to feed the selector:

Definition

<|{sel}|selector|lov={lov}|>
<taipy:selector lov="{lov}">{sel}</taipy:selector>
import taipy.gui.builder as tgb
...
tgb.selector("{sel}", lov="{lov}")

Below is how the selector control appears:

Using icons in the selector items

When using the lov property, the selector's value property will be set to the first element of each tuple in the lov. This allows you to retrieve the unique identifier associated with the selected item (or items).

Display a list of arbitrary objects

The selector control allows any type of object to be used in the list of values (lov) set to the lov property. However, to properly display custom objects, you need to define an adapter function, which must be set to the adapter property. This function instructs the selector on how to identify and represent each item in the list.

Assume your application creates a list of User objects in Python as follows:

class User:
    def __init__(self, id, name, birth_year):
        self.id, self.name, self.birth_year = (id, name, birth_year)

users = [
    User(231, "Johanna", 1987),
    User(125, "John", 1979),
    User(4,   "Peter", 1968),
    User(31,  "Mary", 1974)
    ]

user_sel = users[2]

In this example, a list of User objects is created, with each object having an id, name, and birth year. The variable user_sel is initialized to the third user, "Peter".

The following definition creates a selector that uses this list:

Definition

<|{user_sel}|selector|lov={users}|type=User|adapter={lambda u: (u.id, u.name)}|>
<taipy:selector lov="{users}" type="User" adapter="{lambda u: (u.id, u.name)}">{user_sel}</taipy:selector>
import taipy.gui.builder as tgb
...
tgb.selector("{user_sel}", lov="{users}", type="User", adapter=lambda u: (u.id, u.name))

The users list is set as the value for the selector's lov property.
The value property is bound to the variable user_sel.
The adapter function (set to the adapter property) is a lambda fonction that converts a User instance (whose type name is set to the type property) into a tuple:

  • The first element of the tuple uniquely identifies the item (therefore, those values should be unique among all items).
    In our example, that is simply: u.id.
  • The second element is the text that the selector displays.
    In our example, that is simply: u.name.

Below is how the selector control will appear when using this list of values and adapter function:

Selector using an adapter

The selection (bound to the value property) will be the selected instance of the class User. This allows your application to directly access the selected User object when a choice is made.

Styling

All selector controls are generated with the "taipy-selector" CSS class. You can use this class to target selector controls on your page and apply custom styles.

Stylekit support

The Stylekit provides a specific class, fullwidth, which you can use to style selector controls.

When applied, the fullwidth class ensures that the selector control occupies the entire available horizontal space.

Styling rows

The selector control list is generated as a collection of items grouped in an element that is assigned the "MuiList-root" class. The descendants (the list items) have the "MuiListItemButton-root" class applied.

The optional input field used to set a filter includes the "MuiInputBase-root" class.

Here is an example of a CSS rule that applies to selector controls:

.taipy-selector {
    margin: 0px !important;  /* Global margin */
    .MuiInputBase-root {     /* Input field   */
        background-color: #572c5f38;
        color: #221025;
        border-radius: 0px;
        height: 50px
    }
    .MuiList-root { /* List */
        height: 70vh;      /* Limit height */
        overflow-y: auto;  /* show vertical scroll if necessary */
        .MuiListItemButton-root:nth-child(even) { /* Colors (even) */
            background-color: lightgrey;
            color: darkgrey;
        }
        .MuiListItemButton-root:nth-child(odd) { /* Colors (even) */
            background-color: darkgrey;
            color: lightgrey;
        }
    }
}

This CSS rule:

  • Changes the color of the filter input field;
  • Limits the height of the control;
  • Adds a vertical scrollbar to the selector list if necessary;
  • Changes the colors used by the list items, alternating between two flavors of gray.

Here is how the selector control looks like when this rule is applied:

Styling the selector control