discord.ext.pages – A pagination extension module

New in version 2.0.

This module provides an easy pagination system with buttons, page groups, and custom view support.

Example usage in a cog:

import asyncio

import discord
from discord.commands import SlashCommandGroup
from discord.ext import commands, pages


class PageTest(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.pages = [
            "Page 1",
            [
                discord.Embed(title="Page 2, Embed 1"),
                discord.Embed(title="Page 2, Embed 2"),
            ],
            "Page Three",
            discord.Embed(title="Page Four"),
            discord.Embed(title="Page Five"),
            [
                discord.Embed(title="Page Six, Embed 1"),
                discord.Embed(title="Page Seven, Embed 2"),
            ],
        ]
        self.pages[3].set_image(
            url="https://c.tenor.com/pPKOYQpTO8AAAAAM/monkey-developer.gif"
        )
        self.pages[4].add_field(
            name="Example Field", value="Example Value", inline=False
        )
        self.pages[4].add_field(
            name="Another Example Field", value="Another Example Value", inline=False
        )

        self.more_pages = [
            "Second Page One",
            discord.Embed(title="Second Page Two"),
            discord.Embed(title="Second Page Three"),
        ]

        self.even_more_pages = ["11111", "22222", "33333"]

    def get_pages(self):
        return self.pages

    pagetest = SlashCommandGroup("pagetest", "Commands for testing ext.pages")

    # These examples use a Slash Command Group in a cog for better organization - it's not required for using ext.pages.
    @pagetest.command(name="default")
    async def pagetest_default(self, ctx: discord.ApplicationContext):
        """Demonstrates using the paginator with the default options."""
        paginator = pages.Paginator(pages=self.get_pages())
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="hidden")
    async def pagetest_hidden(self, ctx: discord.ApplicationContext):
        """Demonstrates using the paginator with disabled buttons hidden."""
        paginator = pages.Paginator(pages=self.get_pages(), show_disabled=False)
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="loop")
    async def pagetest_loop(self, ctx: discord.ApplicationContext):
        """Demonstrates using the loop_pages option."""
        paginator = pages.Paginator(pages=self.get_pages(), loop_pages=True)
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="strings")
    async def pagetest_strings(self, ctx: discord.ApplicationContext):
        """Demonstrates passing a list of strings as pages."""
        paginator = pages.Paginator(
            pages=["Page 1", "Page 2", "Page 3"], loop_pages=True
        )
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="timeout")
    async def pagetest_timeout(self, ctx: discord.ApplicationContext):
        """Demonstrates having the buttons be disabled when the paginator view times out."""
        paginator = pages.Paginator(
            pages=self.get_pages(), disable_on_timeout=True, timeout=30
        )
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="remove_buttons")
    async def pagetest_remove(self, ctx: discord.ApplicationContext):
        """Demonstrates using the default buttons, but removing some of them."""
        paginator = pages.Paginator(pages=self.get_pages())
        paginator.remove_button("first")
        paginator.remove_button("last")
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="init")
    async def pagetest_init(self, ctx: discord.ApplicationContext):
        """Demonstrates how to pass a list of custom buttons when creating the Paginator instance."""
        pagelist = [
            pages.PaginatorButton(
                "first", label="<<-", style=discord.ButtonStyle.green
            ),
            pages.PaginatorButton("prev", label="<-", style=discord.ButtonStyle.green),
            pages.PaginatorButton(
                "page_indicator", style=discord.ButtonStyle.gray, disabled=True
            ),
            pages.PaginatorButton("next", label="->", style=discord.ButtonStyle.green),
            pages.PaginatorButton("last", label="->>", style=discord.ButtonStyle.green),
        ]
        paginator = pages.Paginator(
            pages=self.get_pages(),
            show_disabled=True,
            show_indicator=True,
            use_default_buttons=False,
            custom_buttons=pagelist,
            loop_pages=True,
        )
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="emoji_buttons")
    async def pagetest_emoji_buttons(self, ctx: discord.ApplicationContext):
        """Demonstrates using emojis for the paginator buttons instead of labels."""
        page_buttons = [
            pages.PaginatorButton(
                "first", emoji="⏪", style=discord.ButtonStyle.green
            ),
            pages.PaginatorButton("prev", emoji="⬅", style=discord.ButtonStyle.green),
            pages.PaginatorButton(
                "page_indicator", style=discord.ButtonStyle.gray, disabled=True
            ),
            pages.PaginatorButton("next", emoji="➡", style=discord.ButtonStyle.green),
            pages.PaginatorButton("last", emoji="⏩", style=discord.ButtonStyle.green),
        ]
        paginator = pages.Paginator(
            pages=self.get_pages(),
            show_disabled=True,
            show_indicator=True,
            use_default_buttons=False,
            custom_buttons=page_buttons,
            loop_pages=True,
        )
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="custom_buttons")
    async def pagetest_custom_buttons(self, ctx: discord.ApplicationContext):
        """Demonstrates adding buttons to the paginator when the default buttons are not used."""
        paginator = pages.Paginator(
            pages=self.get_pages(),
            use_default_buttons=False,
            loop_pages=False,
            show_disabled=False,
        )
        paginator.add_button(
            pages.PaginatorButton(
                "prev", label="<", style=discord.ButtonStyle.green, loop_label="lst"
            )
        )
        paginator.add_button(
            pages.PaginatorButton(
                "page_indicator", style=discord.ButtonStyle.gray, disabled=True
            )
        )
        paginator.add_button(
            pages.PaginatorButton(
                "next", style=discord.ButtonStyle.green, loop_label="fst"
            )
        )
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="custom_view")
    async def pagetest_custom_view(self, ctx: discord.ApplicationContext):
        """Demonstrates passing a custom view to the paginator."""
        view = discord.ui.View()
        view.add_item(discord.ui.Button(label="Test Button, Does Nothing", row=1))
        view.add_item(
            discord.ui.Select(
                placeholder="Test Select Menu, Does Nothing",
                options=[
                    discord.SelectOption(
                        label="Example Option",
                        value="Example Value",
                        description="This menu does nothing!",
                    )
                ],
            )
        )
        paginator = pages.Paginator(pages=self.get_pages(), custom_view=view)
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="groups")
    async def pagetest_groups(self, ctx: discord.ApplicationContext):
        """Demonstrates using page groups to switch between different sets of pages."""
        page_buttons = [
            pages.PaginatorButton(
                "first", label="<<-", style=discord.ButtonStyle.green
            ),
            pages.PaginatorButton("prev", label="<-", style=discord.ButtonStyle.green),
            pages.PaginatorButton(
                "page_indicator", style=discord.ButtonStyle.gray, disabled=True
            ),
            pages.PaginatorButton("next", label="->", style=discord.ButtonStyle.green),
            pages.PaginatorButton("last", label="->>", style=discord.ButtonStyle.green),
        ]
        view = discord.ui.View()
        view.add_item(discord.ui.Button(label="Test Button, Does Nothing", row=2))
        view.add_item(
            discord.ui.Select(
                placeholder="Test Select Menu, Does Nothing",
                options=[
                    discord.SelectOption(
                        label="Example Option",
                        value="Example Value",
                        description="This menu does nothing!",
                    )
                ],
            )
        )
        page_groups = [
            pages.PageGroup(
                pages=self.get_pages(),
                label="Main Page Group",
                description="Main Pages for Main Things",
            ),
            pages.PageGroup(
                pages=[
                    "Second Set of Pages, Page 1",
                    "Second Set of Pages, Page 2",
                    "Look, it's group 2, page 3!",
                ],
                label="Second Page Group",
                description="Secondary Pages for Secondary Things",
                custom_buttons=page_buttons,
                use_default_buttons=False,
                custom_view=view,
            ),
        ]
        paginator = pages.Paginator(pages=page_groups, show_menu=True)
        await paginator.respond(ctx.interaction, ephemeral=False)

    @pagetest.command(name="update")
    async def pagetest_update(self, ctx: discord.ApplicationContext):
        """Demonstrates updating an existing paginator instance with different options."""
        paginator = pages.Paginator(pages=self.get_pages(), show_disabled=False)
        await paginator.respond(ctx.interaction)
        await asyncio.sleep(3)
        await paginator.update(show_disabled=True, show_indicator=False)

    @pagetest.command(name="target")
    async def pagetest_target(self, ctx: discord.ApplicationContext):
        """Demonstrates sending the paginator to a different target than where it was invoked."""
        paginator = pages.Paginator(pages=self.get_pages())
        await paginator.respond(ctx.interaction, target=ctx.interaction.user)

    @commands.command()
    async def pagetest_prefix(self, ctx: commands.Context):
        """Demonstrates using the paginator with a prefix-based command."""
        paginator = pages.Paginator(pages=self.get_pages(), use_default_buttons=False)
        paginator.add_button(
            pages.PaginatorButton("prev", label="<", style=discord.ButtonStyle.green)
        )
        paginator.add_button(
            pages.PaginatorButton(
                "page_indicator", style=discord.ButtonStyle.gray, disabled=True
            )
        )
        paginator.add_button(
            pages.PaginatorButton("next", style=discord.ButtonStyle.green)
        )
        await paginator.send(ctx)

    @commands.command()
    async def pagetest_target(self, ctx: commands.Context):
        """Demonstrates sending the paginator to a different target than where it was invoked (prefix-command version)."""
        paginator = pages.Paginator(pages=self.get_pages())
        await paginator.send(ctx, target=ctx.author, target_message="Paginator sent!")


def setup(bot):
    bot.add_cog(PageTest(bot))

API Reference

Page

Methods
class discord.ext.pages.Page(content=None, embeds=None, custom_view=None, files=None, **kwargs)

Represents a page shown in the paginator.

Allows for directly referencing and modifying each page as a class instance.

Parameters
await callback(interaction=None)

This function is a coroutine.

The coroutine associated to a specific page. If Paginator.page_action() is used, this coroutine is called.

Parameters

interaction (Optional[discord.Interaction]) – The interaction associated with the callback, if any.

update_files()

Updates the files associated with the page by re-uploading them. Typically used when the page is changed.

property content

Gets the content for the page.

property embeds

Gets the embeds for the page.

property custom_view

Gets the custom view assigned to the page.

property files

Gets the files associated with the page.

Paginator

class discord.ext.pages.Paginator(pages, show_disabled=True, show_indicator=True, show_menu=False, menu_placeholder='Select Page Group', author_check=True, disable_on_timeout=True, use_default_buttons=True, default_button_row=0, loop_pages=False, custom_view=None, timeout=180.0, custom_buttons=None, trigger_on_display=None)

Creates a paginator which can be sent as a message and uses buttons for navigation.

Parameters
  • pages (Union[List[PageGroup], List[Page], List[str], List[Union[List[discord.Embed], discord.Embed]]]) – The list of PageGroup objects, Page objects, strings, embeds, or list of embeds to paginate. If a list of PageGroup objects is provided and show_menu is False, only the first page group will be displayed.

  • show_disabled (bool) – Whether to show disabled buttons.

  • show_indicator (bool) – Whether to show the page indicator when using the default buttons.

  • show_menu (bool) – Whether to show a select menu that allows the user to switch between groups of pages.

  • menu_placeholder (str) – The placeholder text to show in the page group menu when no page group has been selected yet. Defaults to “Select Page Group” if not provided.

  • author_check (bool) – Whether only the original user of the command can change pages.

  • disable_on_timeout (bool) – Whether the buttons get disabled when the paginator view times out.

  • use_default_buttons (bool) – Whether to use the default buttons (i.e. first, prev, page_indicator, next, last)

  • default_button_row (int) – The row where the default paginator buttons are displayed. Has no effect if custom buttons are used.

  • loop_pages (bool) – Whether to loop the pages when clicking prev/next while at the first/last page in the list.

  • custom_view (Optional[discord.ui.View]) – A custom view whose items are appended below the pagination components. If the currently displayed page has a custom_view assigned, it will replace these view components when that page is displayed.

  • timeout (Optional[float]) – Timeout in seconds from last interaction with the paginator before no longer accepting input.

  • custom_buttons (Optional[List[PaginatorButton]]) – A list of PaginatorButtons to initialize the Paginator with. If use_default_buttons is True, this parameter is ignored.

  • trigger_on_display (bool) – Whether to automatically trigger the callback associated with a Page whenever it is displayed. Has no effect if no callback exists for a Page.

menu

The page group select menu associated with this paginator.

Type

Optional[List[PaginatorMenu]]

page_groups

List of PageGroup objects the user can switch between.

Type

Optional[List[PageGroup]]

default_page_group

The index of the default page group shown when the paginator is initially sent. Defined by setting default to True on a PageGroup.

Type

Optional[int]

current_page

A zero-indexed value showing the current page number.

Type

int

page_count

A zero-indexed value showing the total number of pages.

Type

int

buttons

A dictionary containing the PaginatorButton objects included in this paginator.

Type

Dict[str, Dict[str, Union[PaginatorButton, bool]]]

user

The user or member that invoked the paginator.

Type

Optional[Union[User, Member]]

message

The message the paginator is attached to.

Type

Union[Message, WebhookMessage]

await update(pages=None, show_disabled=None, show_indicator=None, show_menu=None, author_check=None, menu_placeholder=None, disable_on_timeout=None, use_default_buttons=None, default_button_row=None, loop_pages=None, custom_view=None, timeout=None, custom_buttons=None, trigger_on_display=None, interaction=None)

Updates the existing Paginator instance with the provided options.

Parameters
  • pages (Optional[Union[List[PageGroup], List[Page], List[str], List[Union[List[discord.Embed], discord.Embed]]]]) – The list of PageGroup objects, Page objects, strings, embeds, or list of embeds to paginate.

  • show_disabled (bool) – Whether to show disabled buttons.

  • show_indicator (bool) – Whether to show the page indicator when using the default buttons.

  • show_menu (bool) – Whether to show a select menu that allows the user to switch between groups of pages.

  • author_check (bool) – Whether only the original user of the command can change pages.

  • menu_placeholder (str) – The placeholder text to show in the page group menu when no page group has been selected yet. Defaults to “Select Page Group” if not provided.

  • disable_on_timeout (bool) – Whether the buttons get disabled when the paginator view times out.

  • use_default_buttons (bool) – Whether to use the default buttons (i.e. first, prev, page_indicator, next, last)

  • default_button_row (Optional[int]) – The row where the default paginator buttons are displayed. Has no effect if custom buttons are used.

  • loop_pages (bool) – Whether to loop the pages when clicking prev/next while at the first/last page in the list.

  • custom_view (Optional[discord.ui.View]) – A custom view whose items are appended below the pagination components.

  • timeout (Optional[float]) – Timeout in seconds from last interaction with the paginator before no longer accepting input.

  • custom_buttons (Optional[List[PaginatorButton]]) – A list of PaginatorButtons to initialize the Paginator with. If use_default_buttons is True, this parameter is ignored.

  • trigger_on_display (bool) – Whether to automatically trigger the callback associated with a Page whenever it is displayed. Has no effect if no callback exists for a Page.

  • interaction (Optional[discord.Interaction]) – The interaction to use when updating the paginator. If not provided, the paginator will be updated by using its stored message attribute instead.

await on_timeout()

Disables all buttons when the view times out.

await disable(include_custom=False, page=None)

Stops the paginator, disabling all of its components.

Parameters
  • include_custom (bool) – Whether to disable components added via custom views.

  • page (Optional[Union[str, Union[List[discord.Embed], discord.Embed]]]) – The page content to show after disabling the paginator.

await cancel(include_custom=False, page=None)

Cancels the paginator, removing all of its components from the message.

Parameters
  • include_custom (bool) – Whether to remove components added via custom views.

  • page (Optional[Union[str, Union[List[discord.Embed], discord.Embed]]]) – The page content to show after canceling the paginator.

await goto_page(page_number=0, *, interaction=None)

Updates the paginator message to show the specified page number.

Parameters
  • page_number (int) –

    The page to display.

    Note

    Page numbers are zero-indexed when referenced internally, but appear as one-indexed when shown to the user.

  • interaction (Optional[discord.Interaction]) – The interaction to use when editing the message. If not provided, the message will be edited using the paginator’s stored message attribute instead.

Returns

The message associated with the paginator.

Return type

Message

await interaction_check(interaction)

This function is a coroutine.

A callback that is called when an interaction happens within the view that checks whether the view should process item callbacks for the interaction.

This is useful to override if, for example, you want to ensure that the interaction author is a given user.

The default implementation of this returns True.

If this returns False, on_check_failure() is called.

Note

If an exception occurs within the body then the check is considered a failure and on_error() is called.

Parameters

interaction (Interaction) – The interaction that occurred.

Returns

Whether the view children’s callbacks should be called.

Return type

bool

add_menu()

Adds the default PaginatorMenu instance to the paginator.

add_default_buttons()

Adds the full list of default buttons that can be used with the paginator. Includes first, prev, page_indicator, next, and last.

add_button(button)

Adds a PaginatorButton to the paginator.

remove_button(button_type)

Removes a PaginatorButton from the paginator.

update_buttons()

Updates the display state of the buttons (disabled/hidden)

Returns

The dictionary of buttons that were updated.

Return type

Dict[str, Dict[str, Union[PaginatorButton, bool]]]

update_custom_view(custom_view)

Updates the custom view shown on the paginator.

get_page_group_content(page_group)

Returns a converted list of Page objects for the given page group based on the content of its pages.

staticmethod get_page_content(page)

Converts a page into a Page object based on its content.

await page_action(interaction=None)

Triggers the callback associated with the current page, if any.

Parameters

interaction (Optional[discord.Interaction]) – The interaction that was used to trigger the page action.

await send(ctx, target=None, target_message=None, reference=None, allowed_mentions=None, mention_author=None, delete_after=None)

Sends a message with the paginated items.

Parameters
  • ctx (Union[Context]) – A command’s invocation context.

  • target (Optional[Messageable]) – A target where the paginated message should be sent, if different from the original Context

  • target_message (Optional[str]) – An optional message shown when the paginator message is sent elsewhere.

  • reference (Optional[Union[discord.Message, discord.MessageReference, discord.PartialMessage]]) – A reference to the Message to which you are replying with the paginator. This can be created using to_reference() or passed directly as a Message. You can control whether this mentions the author of the referenced message using the replied_user attribute of allowed_mentions or by setting mention_author.

  • allowed_mentions (Optional[AllowedMentions]) – Controls the mentions being processed in this message. If this is passed, then the object is merged with allowed_mentions. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in allowed_mentions. If no object is passed at all then the defaults given by allowed_mentions are used instead.

  • mention_author (Optional[bool]) – If set, overrides the replied_user attribute of allowed_mentions.

  • delete_after (Optional[float]) – If set, deletes the paginator after the specified time.

Returns

The message that was sent with the paginator.

Return type

Message

add_item(item)

Adds an item to the view.

Parameters

item (Item) – The item to add to the view.

Raises
  • TypeError – An Item was not passed.

  • ValueError – Maximum number of children has been exceeded (25) or the row the item is trying to be added to is full.

clear_items()

Removes all items from the view.

disable_all_items(*, exclusions=None)

Disables all items in the view.

Parameters

exclusions (Optional[List[Item]]) – A list of items in self.children to not disable from the view.

await edit(message, suppress=None, allowed_mentions=None, delete_after=None)

Edits an existing message to replace it with the paginator contents.

Note

If invoked from an interaction, you will still need to respond to the interaction.

Parameters
  • message (discord.Message) – The message to edit with the paginator.

  • suppress (bool) – Whether to suppress embeds for the message. This removes all the embeds if set to True. If set to False this brings the embeds back if they were suppressed. Using this parameter requires manage_messages.

  • allowed_mentions (Optional[AllowedMentions]) – Controls the mentions being processed in this message. If this is passed, then the object is merged with allowed_mentions. The merging behaviour only overrides attributes that have been explicitly passed to the object, otherwise it uses the attributes set in allowed_mentions. If no object is passed at all then the defaults given by allowed_mentions are used instead.

  • delete_after (Optional[float]) – If set, deletes the paginator after the specified time.

Returns

The message that was edited. Returns None if the operation failed.

Return type

Optional[discord.Message]

enable_all_items(*, exclusions=None)

Enables all items in the view.

Parameters

exclusions (Optional[List[Item]]) – A list of items in self.children to not enable from the view.

classmethod from_message(message, /, *, timeout=180.0)

Converts a message’s components into a View.

The Message.components of a message are read-only and separate types from those in the discord.ui namespace. In order to modify and edit message components they must be converted into a View first.

Parameters
  • message (Message) – The message with components to convert into a view.

  • timeout (Optional[float]) – The timeout of the converted view.

Returns

The converted view. This always returns a View and not one of its subclasses.

Return type

View

get_item(custom_id)

Get an item from the view with the given custom ID. Alias for utils.get(view.children, custom_id=custom_id).

Parameters

custom_id (str) – The custom_id of the item to get

Returns

The item with the matching custom_id if it exists.

Return type

Optional[Item]

is_dispatching()

bool: Whether the view has been added for dispatching purposes.

is_finished()

bool: Whether the view has finished interacting.

is_persistent()

bool: Whether the view is set up as persistent.

A persistent view has all their components with a set custom_id and a timeout set to None.

await on_check_failure(interaction)

This function is a coroutine. A callback that is called when a View.interaction_check() returns False. This can be used to send a response when a check failure occurs.

Parameters

interaction (Interaction) – The interaction that occurred.

await on_error(error, item, interaction)

This function is a coroutine.

A callback that is called when an item’s callback or interaction_check() fails with an error.

The default implementation prints the traceback to stderr.

Parameters
  • error (Exception) – The exception that was raised.

  • item (Item) – The item that failed the dispatch.

  • interaction (Interaction) – The interaction that led to the failure.

remove_item(item)

Removes an item from the view.

Parameters

item (Item) – The item to remove from the view.

stop()

Stops listening to interaction events from this view.

This operation cannot be undone.

await wait()

Waits until the view has finished interacting.

A view is considered finished when stop() is called, or it times out.

Returns

If True, then the view timed out. If False then the view finished normally.

Return type

bool

await respond(interaction, ephemeral=False, target=None, target_message='Paginator sent!')

Sends an interaction response or followup with the paginated items.

Parameters
  • interaction (Union[discord.Interaction, BridgeContext]) – The interaction or BridgeContext which invoked the paginator. If passing a BridgeContext object, you cannot make this an ephemeral paginator.

  • ephemeral (bool) –

    Whether the paginator message and its components are ephemeral. If target is specified, the ephemeral message content will be target_message instead.

    Warning

    If your paginator is ephemeral, it cannot have a timeout longer than 15 minutes (and cannot be persistent).

  • target (Optional[Messageable]) – A target where the paginated message should be sent, if different from the original discord.Interaction

  • target_message (str) – The content of the interaction response shown when the paginator message is sent elsewhere.

Returns

The Message or WebhookMessage that was sent with the paginator.

Return type

Union[Message, WebhookMessage]

PaginatorButton

class discord.ext.pages.PaginatorButton(button_type, label=None, emoji=None, style=<ButtonStyle.success: 3>, disabled=False, custom_id=None, row=0, loop_label=None)

Creates a button used to navigate the paginator.

Parameters
  • button_type (str) – The type of button being created. Must be one of first, prev, next, last, or page_indicator.

  • label (str) – The label shown on the button. Defaults to a capitalized version of button_type (e.g. “Next”, “Prev”, etc.)

  • emoji (Union[str, discord.Emoji, discord.PartialEmoji]) – The emoji shown on the button in front of the label.

  • disabled (bool) – Whether to initially show the button as disabled.

  • loop_label (str) – The label shown on the button when loop_pages is set to True in the Paginator class.

paginator

The paginator class where this button is being used. Assigned to the button when Paginator.add_button is called.

Type

Paginator

property label

The label of the button, if available.

Type

Optional[str]

property emoji

The emoji of the button, if available.

Type

Optional[PartialEmoji]

property style

The style of the button.

Type

discord.ButtonStyle

property disabled

Whether the button is disabled or not.

Type

bool

await callback(interaction)

This function is a coroutine.

The coroutine that is called when the navigation button is clicked.

Parameters

interaction (discord.Interaction) – The interaction created by clicking the navigation button.

property custom_id

The ID of the button that gets received during an interaction.

If this button is for a URL, it does not have a custom ID.

Type

Optional[str]

property url

The URL this button sends you to.

Type

Optional[str]

property view

The underlying view for this item.

Type

Optional[View]

PaginatorMenu

class discord.ext.pages.PaginatorMenu(page_groups, placeholder=None, custom_id=None)

Creates a select menu used to switch between page groups, which can each have their own set of buttons.

Parameters

placeholder (str) – The placeholder text that is shown if nothing is selected.

paginator

The paginator class where this menu is being used. Assigned to the menu when Paginator.add_menu is called.

Type

Paginator

add_option(*, label, value=..., description=None, emoji=None, default=False)

Adds an option to the select menu.

To append a pre-existing discord.SelectOption use the append_option() method instead.

Parameters
  • label (str) – The label of the option. This is displayed to users. Can only be up to 100 characters.

  • value (str) – The value of the option. This is not displayed to users. If not given, defaults to the label. Can only be up to 100 characters.

  • description (Optional[str]) – An additional description of the option, if any. Can only be up to 100 characters.

  • emoji (Optional[Union[str, Emoji, PartialEmoji]]) – The emoji of the option, if available. This can either be a string representing the custom or unicode emoji or an instance of PartialEmoji or Emoji.

  • default (bool) – Whether this option is selected by default.

Raises

ValueError – The number of options exceeds 25.

append_option(option)

Appends an option to the select menu.

Parameters

option (discord.SelectOption) – The option to append to the select menu.

Raises

ValueError – The number of options exceeds 25.

property custom_id

The ID of the select menu that gets received during an interaction.

Type

str

property disabled

Whether the select is disabled or not.

Type

bool

property max_values

The maximum number of items that must be chosen for this select menu.

Type

int

property min_values

The minimum number of items that must be chosen for this select menu.

Type

int

property options

A list of options that can be selected in this menu.

Type

List[discord.SelectOption]

property placeholder

The placeholder text that is shown if nothing is selected, if any.

Type

Optional[str]

property values

A list of values that have been selected by the user.

Type

List[str]

property view

The underlying view for this item.

Type

Optional[View]

await callback(interaction)

This function is a coroutine.

The coroutine that is called when a menu option is selected.

Parameters

interaction (discord.Interaction) – The interaction created by selecting the menu option.

PageGroup

class discord.ext.pages.PageGroup(pages, label, description=None, emoji=None, default=None, show_disabled=None, show_indicator=None, author_check=None, disable_on_timeout=None, use_default_buttons=None, default_button_row=0, loop_pages=None, custom_view=None, timeout=None, custom_buttons=None, trigger_on_display=None)

Creates a group of pages which the user can switch between.

Each group of pages can have its own options, custom buttons, custom views, etc.

Note

If multiple PageGroup objects have different options, they should all be set explicitly when creating each instance.

Parameters
  • pages (Union[List[str], List[Page], List[Union[List[discord.Embed], discord.Embed]]]) – The list of Page objects, strings, embeds, or list of embeds to include in the page group.

  • label (str) – The label shown on the corresponding PaginatorMenu dropdown option. Also used as the SelectOption value.

  • description (Optional[str]) – The description shown on the corresponding PaginatorMenu dropdown option.

  • emoji (Union[str, discord.Emoji, discord.PartialEmoji]) – The emoji shown on the corresponding PaginatorMenu dropdown option.

  • default (Optional[bool]) – Whether the page group should be the default page group initially shown when the paginator response is sent. Only one PageGroup can be the default page group.

  • show_disabled (bool) – Whether to show disabled buttons.

  • show_indicator (bool) – Whether to show the page indicator when using the default buttons.

  • author_check (bool) – Whether only the original user of the command can change pages.

  • disable_on_timeout (bool) – Whether the buttons get disabled when the paginator view times out.

  • use_default_buttons (bool) – Whether to use the default buttons (i.e. first, prev, page_indicator, next, last)

  • default_button_row (int) – The row where the default paginator buttons are displayed. Has no effect if custom buttons are used.

  • loop_pages (bool) – Whether to loop the pages when clicking prev/next while at the first/last page in the list.

  • custom_view (Optional[discord.ui.View]) – A custom view whose items are appended below the pagination buttons.

  • timeout (Optional[float]) – Timeout in seconds from last interaction with the paginator before no longer accepting input.

  • custom_buttons (Optional[List[PaginatorButton]]) – A list of PaginatorButtons to initialize the Paginator with. If use_default_buttons is True, this parameter is ignored.

  • trigger_on_display (bool) – Whether to automatically trigger the callback associated with a Page whenever it is displayed. Has no effect if no callback exists for a Page.