Multiselect#

Multiselect is another kind of stateful selection widget. It very similar to Radio but remembers multiple selected items

Same as for Radio you should pass two texts (for checked and unchecked items). Passed data is the same as for Select

import operator

from aiogram_dialog.widgets.kbd import Multiselect
from aiogram_dialog.widgets.text import Format


# let's assume this is our window data getter
async def get_data(**kwargs):
    fruits = [
        ("Apple", '1'),
        ("Pear", '2'),
        ("Orange", '3'),
        ("Banana", '4'),
    ]
    return {
        "fruits": fruits,
        "count": len(fruits),
    }


fruits_kbd = Multiselect(
    Format("✓ {item[0]}"),  # E.g `✓ Apple`
    Format("{item[0]}"),
    id="m_fruits",
    item_id_getter=operator.itemgetter(1),
    items="fruits",
)

After few clicks it will look like:

../../../_images/multiselect.png

Other useful options are:

  • min_selected - limits minimal number of selected items ignoring clicks if this restriction is violated. It does not affect initial state.

  • max_selected - limits maximal number of selected items

  • on_state_changed - callback function. Called when item changes selected state

To work with selection you can use this methods:

  • get_checked - returns a list of ids of all selected items

  • is_checked - returns if certain id is currently selected

  • set_checked - changes selection state of provided id

  • reset_checked - resets all checked items to unchecked state

Warning

Multiselect widgets stores state of all checked items even if they disappear from window data. It is very useful when you have pagination, but might be unexpected when data is really removed.

Classes#

class aiogram_dialog.widgets.kbd.select.OnItemStateChanged(*args, **kwargs)#
abstract async __call__(event, select, dialog_manager, data)#

Call self as a function.

Parameters:

  • event (CallbackQuery | Message | DialogUpdateEvent | ChatMemberUpdated | ChatJoinRequest) –

  • select (ManagedT) –

  • dialog_manager (DialogManager) –

  • data (T) –

class aiogram_dialog.widgets.kbd.select.OnItemClick(*args, **kwargs)#
abstract async __call__(event, select, dialog_manager, data, /)#

Call self as a function.

Parameters:

  • event (CallbackQuery) –

  • select (ManagedT) –

  • dialog_manager (DialogManager) –

  • data (T) –

class aiogram_dialog.widgets.kbd.Multiselect(checked_text, unchecked_text, id, item_id_getter, items, min_selected=0, max_selected=0, type_factory=<class 'str'>, on_click=None, on_state_changed=None, when=None)#
Parameters:

  • checked_text (Text) –

  • unchecked_text (Text) –

  • id (str) –

  • item_id_getter (Callable[[Any], str | int]) –

  • items (str | Callable[[Dict], Sequence] | MagicFilter | Sequence) –

  • min_selected (int) –

  • max_selected (int) –

  • type_factory (Callable[[str], T]) –

  • on_click (OnItemClick[ManagedMultiselect[T], T] | WidgetEventProcessor | None) –

  • on_state_changed (OnItemStateChanged[ManagedMultiselect[T], T] | WidgetEventProcessor | None) –

  • when (str | Callable) –

__init__(checked_text, unchecked_text, id, item_id_getter, items, min_selected=0, max_selected=0, type_factory=<class 'str'>, on_click=None, on_state_changed=None, when=None)#
Parameters:

  • checked_text (Text) –

  • unchecked_text (Text) –

  • id (str) –

  • item_id_getter (Callable[[Any], str | int]) –

  • items (str | Callable[[Dict], Sequence] | MagicFilter | Sequence) –

  • min_selected (int) –

  • max_selected (int) –

  • type_factory (Callable[[str], T]) –

  • on_click (OnItemClick[ManagedMultiselect[T], T] | WidgetEventProcessor | None) –

  • on_state_changed (OnItemStateChanged[ManagedMultiselect[T], T] | WidgetEventProcessor | None) –

  • when (str | Callable | None) –

class aiogram_dialog.widgets.kbd.ManagedMultiselect(widget, manager)#
Parameters:

  • widget (W) –

  • manager (DialogManager) –

get_checked()#

Get a list of checked items ids.

Return type:

List[T]

is_checked(item_id)#

Get if an item identified by item_id is checked.

Parameters:

item_id (T) –

Return type:

bool

async reset_checked()#

Reset all items to their default state.

async set_checked(item_id, checked)#

Set an item identified by item_id as checked or unchecked.

Parameters:

  • item_id (T) –

  • checked (bool) –

Return type:

None