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 |
---|---|---|---|
(★) |
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:
|
|
dropdown |
bool |
False | If True, the list of items is shown in a dropdown menu. |
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]). |
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).
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.
|
|
propagate |
bool |
App config | Allows the control's main value to be automatically propagated. |
active |
bool dynamic |
True | Indicates if this component is active. |
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. |
|
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:
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 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. The multiple property is automatically set to True.
-
When the mode is set to "radio", the control displays as a list of radio buttons. 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:
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:
Clicking the drop-down button reveals the full 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:
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:
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:
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:
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: