ListGroup

ListGroup is more complex way to render widgets for list of items. While Select generates simple buttons, with ListGroup you can create any set of keyboard widgets and repeat them.

To identity item inside keyboard event you can check dialog_manager.item_id. This is possible because SubManager is passed instead of DialogManager while corresponding widget is located inside ListGroup.

To find widget for specific item_id in a ListGroup, you can use the .find_for_item method from ManagedListGroup.

Manager methods:

  • .find: if manager already adapted for current ListGroup row, finds the widget within the current manager (SubManager).

  • .find_in_parent: if you need to find widgets outside the row, finds the widget within the parent manager (DialogManager).

Note

If you nest a ListGroup in ListGroup your parent manager will be SubManager

Additionally, you can provide page_size and id so the ListGroup will allow you to paginate its items. You can combine it with Pager widgets to switch pages.

Code example:

from aiogram import F
from aiogram.filters.state import State, StatesGroup
from aiogram_dialog import (
    Window,
    Dialog,
)
from aiogram_dialog.widgets.kbd import (
    Url,
    ListGroup,
    SwitchTo,
    Back,
)
from aiogram_dialog.widgets.text import Const, Format


class SG(StatesGroup):
    main = State()
    result = State()


success = F["products"]
fail = ~success


async def actions(**kwargs):
    products = [
        {"id": 1, "name": "Ferrari", "category": "car",
         "url": "https://www.ferrari.com/"},
        {"id": 2, "name": "Detroit", "category": "game",
         "url": "https://wikipedia.org/wiki/Detroit:_Become_Human"},
    ]
    return {
        "products": products,
    }


dialog = Dialog(
    Window(
        Const("Click find products to show a list of available products:"),
        SwitchTo(Const("Find products"), id="search", state=SG.result),
        state=SG.main,
    ),
    Window(
        Const("Searching results:", when=success),
        Const("Search did not return any results", when=fail),
        ListGroup(
            Url(
                Format("{item[name]} ({item[category]})"),
                Format("{item[url]}"),
                id="url",
            ),
            id="select_search",
            item_id_getter=lambda item: item["id"],
            items="products",
        ),
        Back(Const("Back")),
        state=SG.result,
        getter=actions,
    )
)
class aiogram_dialog.widgets.kbd.ListGroup(*buttons, id, item_id_getter, items, when=None, page_size=0, on_page_changed=None)
Parameters:

  • buttons (Keyboard)

  • id (str)

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

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

  • when (str | MagicFilter | Predicate | None)

  • page_size (int)

  • on_page_changed (Callable[[CallbackQuery | ChatJoinRequest | ChatMemberUpdated | DialogUpdateEvent | ErrorEvent | Message, ManagedScroll, DialogManager], Awaitable] | WidgetEventProcessor | None)

__init__(*buttons, id, item_id_getter, items, when=None, page_size=0, on_page_changed=None)
Parameters:

  • buttons (Keyboard)

  • id (str)

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

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

  • when (str | MagicFilter | Predicate | None)

  • page_size (int)

  • on_page_changed (Callable[[CallbackQuery | ChatJoinRequest | ChatMemberUpdated | DialogUpdateEvent | ErrorEvent | Message, ManagedScroll, DialogManager], Awaitable] | WidgetEventProcessor | None)

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

  • widget (W)

  • manager (DialogManager)

find_for_item(widget_id, item_id)

Find widget for specific item_id.

Parameters:

  • widget_id (str)

  • item_id (str)

Return type:

Any | None

class aiogram_dialog.manager.sub_manager.SubManager(widget, manager, widget_id, item_id)
Parameters:

  • widget (Widget)

  • manager (DialogManager)

  • widget_id (str)

  • item_id (str)