Skip to content
taipy

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).

Default value in the Page Builder API

A known issue in Taipy GUI 3.1 is that you cannot use the default value when creating a selector with the Page Builder API. You must explicitly set the value parameter:

tgb.selector("{my_var}") will not work properly.

You have to call: tgb.selector(value="{my_var}") to fix that problem.

Properties

Name Type Default Description
value(★) any
dynamic

Bound to the selection value.
filter bool False

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

If True, the user can select multiple items.
width str|int "360px"

The width, in CSS units, of this element.
height str|int

The height, in CSS units, of this element.
dropdown bool False

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

You cannot use the filter in that situation.
label str None

The label associated with the selector when in dropdown mode.
mode str

Define the way the selector is displayed:

  • "radio": list of radio buttons
  • "check": list of check buttons
  • any other value: selector as usual.
lov dict[str, any]

The list of values. See the section on List of Values for details.
adapter Function `lambda x: str(x)`

The function that transforms an element of lov into a tuple(id:str, label:str|Icon).
type str Type of first lov element

Must be specified if lov contains a non-specific type of data (ex: dict).
value must be of that type, lov must be an iterable on this type, and the adapter function will receive an object of this type.
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 Callback

The name of a function that is triggered when the value is updated.
The parameters of that function are all optional:

  • 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.
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 will be 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 will be associated with the generated HTML Element.
These class names will be added to the default taipy-<element_type>.
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 texts:

A selector with several items

The user can select an item that appears highlighted in the control.

If the multiple property is True, then the list appears as a series of toggle buttons that users can select and deselect:

Multiple selection

Then several items can be selected, and the value property is set to an array that stores those items.

Display modes

The mode property can be set to "check" or "radio" to change the way the selector is represented:

  • If mode is set to "check", the control displays as a list of toggle buttons:

    "check" mode

    The multiple property is forced to True.

  • If mode is set to "radio", the control displays a list of radio buttons:

    "radio" mode

    The multiple property is forced to False.

Styling

All the selector controls are generated with the "taipy-selector" CSS class. You can use this class name to select the selector controls on your page and apply style.

Stylekit support

The Stylekit provides a specific class that you can use to style selector controls:

  • fullwidth
    If a selector control uses the fullwidth class, it uses the whole available horizontal space.

Usage

Display a list of string

You can create a selector on a series of strings:

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="{value}", lov="Item 1;Item 2;Item 3")

Display as a dropdown

You can set the dropdown property to True to make the selector control a drop-down selector.

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="{value}", lov="Item 1;Item 2;Item 3", dropdown=True)

Display with filter and multiple selection

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

Definition

<|{value}|selector|lov=Item 1;Item 2;Item 3|filter|multiple|>

<taipy:selector lov="Item 1;Item 2;Item 3" filter multiple>{value}</taipy:selector>

import taipy.gui.builder as tgb
...
tgb.selector(value="{value}", lov="Item 1;Item 2;Item 3", filter=True, multiple=True)

Display a list of tuples

A selector control that returns an id while selecting a label or Icon.

Definition

<|{sel}|selector|lov={[("id1", "Label 1"), ("id2", Icon("/images/icon.png", "Label 2"),("id3", "Label 3")]}|>

<taipy:selector lov="{[('id1', 'Label 1'), ('id2', Icon('/images/icon.png', 'Label 2'),('id3', 'Label 3')]}">{sel}</taipy:selector>

import taipy.gui.builder as tgb
...
tgb.selector(value="{sel}", lov="{[('id1', 'Label 1'), ('id2', Icon('/images/icon.png', 'Label 2'),('id3', 'Label 3')]}")

Display a list of objects

Assuming your Python code has created a list of object: 

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]

If you want to create a selector control that lets you pick a specific user, you can use the following fragment.

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(value="{user_sel}", lov="{users}", type="User", adapter="{lambda u: (u.id, u.name)}")

In this example, we use the Python list users as the selector's list of values.
Because the control needs a way to convert the list items (which are instances of the class User) into displayable strings, we are using an adapter: a function that converts an object, whose type must be provided to the type property, to a tuple. The first element of the tuple is used to reference the selection (therefore, those elements should be unique among all the items), and the second element is the string that turns out to be displayed.