Paginators¶

See here the various paginators available in this package.

Buttons¶

class discord.ext.paginators.button_paginator.ButtonPaginator(pages, *, buttons={}, always_show_stop_button=False, combine_switcher_and_stop_button=False, style_if_clickable=..., **kwargs)[source]¶

Bases: BaseClassPaginator[PageT]

A paginator that uses buttons to switch pages.

This class has a few parameters that differ from the base paginator.

Just for clarification, here is a list of supported pages:

See other parameters on BaseClassPaginator.

Parameters:

buttons (Dict[str, PaginatorButton]) –

A dictionary of buttons to use. The keys must be one of the following: “FIRST”, “LEFT”, “RIGHT”, “LAST”, “STOP”, “PAGE_INDICATOR”. The values must be a PaginatorButton or None to remove the button. If not specified, the default buttons will be used.

Example

from discord.ext.paginators.button_paginator import ButtonPaginator, PaginatorButton

custom_buttons = {
    # change the label of the first button from "First" to "Go to first page"
    "FIRST": PaginatorButton(label="Go to first page"),
    # change the style of the LAST button to red
    "LAST": PaginatorButton(style=ButtonStyle.red),
}

# pass the custom buttons to the paginator
paginator = ButtonPaginator(pages, buttons=custom_buttons)
... # rest of code

always_show_stop_button (bool) –
Whether to always show the stop button, even if there is only one page. Defaults to False.

Note

If always_show_stop_button is True, the STOP key in buttons cannot be None.
combine_switcher_and_stop_button (bool) –
Whether to combine the page switcher and stop button into the paginator indicator which will send another set of buttons to switch pages and stop the paginator as an ephemeral message when clicked. Defaults to False.

Note

If combine_switcher_and_stop_button is True, the STOP and PAGE_INDICATOR keys in buttons cannot be None.
style_if_clickable (discord.ButtonStyle) –
The style to change the buttons that are not disabled / clickable to and changes them back to the original style otherwise. Defaults to discord.ButtonStyle.green. Pass None to disable this feature.

Added in version 0.3.0.
**kwargs (Unpack[BasePaginatorKwargs]) – See other parameters on discord.ext.paginator.base_paginator.BaseClassPaginator.
pages (Sequence[Any])

class discord.ext.paginators.button_paginator.PaginatorButton(*, emoji=None, label=None, custom_id=None, style=('primary', 1), row=None, disabled=False, position=None)[source]¶

Bases: Button[ButtonPaginator[Any] | PageSwitcherAndStopButtonView]

A button for the paginator.

This class has a few parameters that differ from the base button. This can can be used passed to the buttons parameter in ButtonPaginator to customize the buttons used.

See other parameters on discord.ui.Button.

Parameters:

position (Optional[int]) – The position of the button. Defaults to None. If not specified, the button will be placed in the order they were added or whatever order discord.py adds them in.
emoji (Optional[Emoji, PartialEmoji, str]] (default: None))
label (Optional[str] (default: None))
custom_id (Optional[str] (default: None))
style (ButtonStyle (default: <ButtonStyle.primary: 1>))
row (Optional[int] (default: None))
disabled (bool (default: False))

Selects¶

class discord.ext.paginators.select_paginator.SelectOptionsPaginator(pages, *, per_select=..., set_default_on_switch=True, set_default_on_select=True, add_in_order=False, default_option=None, **kwargs)[source]¶

Bases: BaseClassPaginator[PageT]

A paginator that uses discord.ui.Select to select pages.

This paginator provides one select and two buttons to navigate through “pages” with options.

Just for clarification, here is a list of supported pages:

discord.Embed
discord.File
discord.Attachment
str
list or tuple of the above
PaginatorOption (a subclass of discord.SelectOption with a content kwarg that can be any of the above)

Other parameters are the same as discord.ext.paginators.base_paginator.BaseClassPaginator. Except per_page which is always 1 and cannot be changed.

Parameters:

pages (Sequence[Union[Any, PaginatorOption]]) –
A sequence of pages to paginate through. A page can be anything that is supported by the BaseClassPaginator class. With the addition of PaginatorOption which is a subclass of discord.SelectOption that also contains a content attribute, it can be used to provide a custom label, description and emoji for each “page”.

All options will be split into chunks of per_select and each chunk will be a select. IF a chunk is a already a list, it will be treated as a single select. If this chunk contains less or more items than per_select, it will raise a ValueError.

Example:
```
pages = [
    # This will be a single select with 3 options
    # per_select must be >= 3 or it will raise a ValueError
    ["Page 1", "Page 2", "Page 3"],
    # These will span across the needed amount of selects
    "Page 4", "Page 5", "Page 6", "Page 7",
    ...
]
```
Note that a nested list ([1, 2, 3, [4, 5, 6]]) is not supported.
per_select (Optional[int]) – The amount of options per select. Defaults to SelectOptionsPaginator.MAX_SELECT_OPTIONS.

add_in_order (bool) –

Whether to add the options in the order they are provided. Defaults to False. False will add the option in whatever order the library parses them.

Example

# if True
pages = [
    | <page 1>, |
    | <page 2>, |
    | <page 3>, |
    # this ^ will be a single select with 3 options
    [<page 4>, <page 5>, <page 6>, <page 7>],
    # this ^ will be a single select with 4 options
    | <page 7>, |
    # this ^ will be a single select with 1 option
    [<page 8>, <page 9>, <page 10>],
    # this ^ will be a single select with 3 options
    ...
    # and so on
]

# if False
pages = [
    <page 1>,
    <page 2>,
    <page 3>,
    [<page 4>, <page 5>, <page 6>, <page 7>],
    # this ^ will be a single select with 4 options
    <page 7>,
    [<page 8>, <page 9>, <page 10>],
    # this ^ will be a single select with 3 options
    ...
    # and so on

    # pages 1, 2, 3 and 7 will be in one select.
]

Make sure to experiment with this to see what fits your needs the best.

Added in version 0.3.0.

set_default_on_switch (bool) –
Whether to set the first option of each “page” as the default option.

This is also used when sending the paginator for the first time.

Defaults to True.

Added in version 0.3.0.
set_default_on_select (bool) –
Whether to set the selected option as the default option. Defaults to True.

Added in version 0.3.0.
default_option (Optional[discord.SelectOption]) –
The option to get the metadata from if the a page is not an instance of PaginatorOption. If this is None, it will try to get the metadata from the page itself. E,g if the page is an embed, it will try to get the title or description, etc and use that as the label.

Defaults to None.

Deprecated since version 0.3.0: This parameter is deprecated and will be removed in a future version. It is recommended to use PaginatorOption instead.
kwargs (Unpack[BasePaginatorKwargs[Self]])

MAX_SELECT_OPTIONS: ClassVar[Literal[25]] = 25¶: The maximum amount of options per select by discord by the time of writing this.

property current_page: int¶

The current page. Starts from 0.

Type:: int

async format_page(page)[source]¶

This method can be overridden to format the page before sending it. By default, it returns the page’s content.

Parameters:

page (PaginatorOption) –

The option to format.

Use the content attribute to get the contents of the page.

Changed in version 0.3.0: This is now the selected option instead of the page’s contents.

Returns:

Union[Any], Sequence[Any]] – The formatted page(s).

Return type:

TypeAliasForwardRef(‘Any’) | Sequence[TypeAliasForwardRef(‘Any’)]

get_page(page_number)[source]¶

Gets the page with the given page number.

Parameters:: page_number (int) – The page number to get.
Returns:: Union[Any], Sequence[Any]] – The page(s) with the given page number.
Return type:: PaginatorOption[TypeAliasForwardRef(‘Any’)]

async on_select(interaction, option)[source]¶

This method is called when an option is selected.

This method can be overridden to provide custom behavior when an option is selected. This method is called after the select is updated and does nothing by default.

Added in version 0.3.0.

Parameters:

interaction (discord.Interaction) – The interaction that triggered the select.
option (PaginatorOption) – The selected option.

Return type:

None

class discord.ext.paginators.select_paginator.PaginatorOption(content, *, label=..., emoji=None, value=..., description=None)[source]¶

Bases: SelectOption, Generic[PageT]

A subclass of discord.SelectOption representing a page in a SelectOptionsPaginator.

Other parameters are the same as SelectOption.

Parameters:

content (Union[Any, Sequence[Any]]) – The content of the page. See SelectOptionsPaginator for more the supported types.
emoji (Optional[Union[str, discord.Emoji, discord.PartialEmoji]]) – The emoji to use for the option. Defaults to None.
label (str (default: ...))
value (str (default: ...))
description (Optional[str] (default: None))