toggle

A series of toggle buttons that the user can select.

Properties¶

Name	Type	Default	Description
`value`^(★)	`Any` dynamic		Bound to the selection value.
`theme`	`bool`	False	If set, this toggle control acts as a way to set the application Theme (dark or light).
`allow_unselect`	`bool`	False	If set, this allows de-selection and the value is set to unselected_value.
`unselected_value`	`Any`	None	Value assigned to value when no item is selected.
`mode`	`str`		Define the way the toggle is displayed: "theme": synonym for setting the theme property to True
`label`	`str`		The label associated with the toggle.
`width`	`Union[str, int]`	None	The width of the element.
`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-toggle` 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¶

You can use a string, an image, or both in each button.

A typical representation would be like this image:

In this example, the lov property of the control is a list of three string elements. If the user selects one of the elements, value is updated accordingly to the selected string.

Note that if the variable bound to value is a Boolean value, then the control displays a switch control:

Toggle control bound to a Boolean variable

The property value reflects the control's status as a Boolean value.

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

Usage¶

Display a list of string¶

You can create a list of toggle buttons from a series of strings:

Definition

MarkdownHTMLPython

<|{value}|toggle|lov=Item 1;Item 2;Item 3|>

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

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

Unselect value¶

In a toggle control, all buttons might be unselected. Therefore there is no value selected. In that case, the value of the property unselected_value is assigned if specified.

Definition

MarkdownHTMLPython

<|{value}|toggle|lov=Item 1;Item 2;Item 3|unselected_value=No Value|>

<taipy:toggle lov="Item 1;Item 2;Item 3" unselected_value="No Value">{value}</taipy:toggle>

import taipy.gui.builder as tgb
...
tgb.toggle("{value}", lov="Item 1;Item 2;Item 3", unselected_value="No Value")

Display a list of tuples¶

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

Definition

MarkdownHTMLPython

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

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

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

Use arbitrary objects¶

Assuming your Python code has created a list of objects:

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 toggle control that lets you pick a specific user, you can use the following fragment:

Definition

MarkdownHTMLPython

<|{user_sel}|toggle|lov={users}|type=User|adapter={lambda u: (u.id, u.name)}|>

<taipy:toggle lov="{users}" type="User" adapter="{lambda u: (u.id, u.name)}">{user_sel}</taipy:toggle>

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

In this example, we are using the Python list users as the toggle's list of values. Because the control needs a way to convert the list items (which are instances of the class User) into a string that can be displayed, 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.

Styling¶

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

The Stylekit also provides specific CSS classes that you can use to style toggle controls:

relative
Resets the theme toggle position in the page flow (especially for the theme mode toggle).
nolabel
Hides the toggle control's label.
taipy-navbar
Gives the toggle control the look and feel of a navbar.