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.
selection_message	str dynamic		The message shown in the selection area of a dropdown selector when at least one element is selected. If None, the message is the list of all the selected elements.
multiple	bool	False	If True, the user can select multiple items.
show_select_all	bool	False	If True and multiple is True, the selector shows a "Select all option" button.
filter	bool	False	If True, this control is combined with a filter input area.
width	Union[str, int]	"360px"	The width of the selector, in CSS units.
height	Union[str, int]		The height of the 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 changes. The callback function receives the following parameters: state (State): the state instance. var_name (str): the bound variable name. value (Any): the updated value.
propagate	bool	App config	Determines whether the control's value is automatically reflected in the bound application variable. 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 variable.
active	bool dynamic	True	Indicates if this element is active. If False, the element is disabled, and user interaction is not allowed.
id	str		The identifier assigned to the rendered HTML component. This can be used in callbacks or to target the element for styling.
properties	dict[str, Any]		A dictionary of additional properties that can be set to the element.
class_name	str dynamic		A space-separated list of CSS class names to be applied to the generated HTML element. These classes are added to the default taipy-selector class.
hover_text	str dynamic		The text that is displayed when the user hovers over the 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

See the entire code for this example

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

MarkdownHTMLPython

<|{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

See the entire code for this example

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

Definition

MarkdownHTMLPython

<|{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

See the entire code for this example

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

MarkdownHTMLPython

<|{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

See the entire code for this example

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

MarkdownHTMLPython

<|{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

See the entire code for this example

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

MarkdownHTMLPython

<|{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

See the entire code for this example

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