discord.ext.pages#

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)[source]#

Represents a page shown in the paginator.

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

Parameters:
await callback(interaction=None)[source]#

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()[source]#

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

Return type:

Optional[List[File]]

property content#

Gets the content for the page.

Return type:

Optional[str]

property embeds#

Gets the embeds for the page.

Return type:

Optional[List[Union[List[Embed], Embed]]]

property custom_view#

Gets the custom view assigned to the page.

Return type:

Optional[View]

property files#

Gets the files associated with the page.

Return type:

Optional[List[File]]

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)[source]#

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)[source]#

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()[source]#

Disables all buttons when the view times out.

Return type:

None

await disable(include_custom=False, page=None)[source]#

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.

Return type:

None

await cancel(include_custom=False, page=None)[source]#

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.

Return type:

None

await goto_page(page_number=0, *, interaction=None)[source]#

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)[source]#

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()[source]#

Adds the default PaginatorMenu instance to the paginator.

add_default_buttons()[source]#

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)[source]#

Adds a PaginatorButton to the paginator.

Parameters:

button (PaginatorButton) –

remove_button(button_type)[source]#

Removes a PaginatorButton from the paginator.

Parameters:

button_type (str) –

update_buttons()[source]#

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)[source]#

Updates the custom view shown on the paginator.

Parameters:

custom_view (View) –

get_page_group_content(page_group)[source]#

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

Parameters:

page_group (PageGroup) –

Return type:

List[Page]

staticmethod get_page_content(page)[source]#

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

Parameters:

page (Union[Page, str, Embed, List[Embed]]) –

Return type:

Page

await page_action(interaction=None)[source]#

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.

Return type:

None

await send(ctx, target=None, target_message=None, reference=None, allowed_mentions=None, mention_author=None, delete_after=None)[source]#

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.

Return type:

None

clear_items()#

Removes all items from the view.

Return type:

None

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)[source]#

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()#

Whether the view has been added for dispatching purposes.

Return type:

bool

is_finished()#

Whether the view has finished interacting.

Return type:

bool

is_persistent()#

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.

Return type:

bool

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.

Return type:

None

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.

Return type:

None

remove_item(item)#

Removes an item from the view.

Parameters:

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

Return type:

None

stop()#

Stops listening to interaction events from this view.

This operation cannot be undone.

Return type:

None

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!')[source]#

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)[source]#

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

Parameters:
property label#

The label of the button, if available.

Return type:

str | None

property emoji#

The emoji of the button, if available.

Return type:

PartialEmoji | None

property style#

The style of the button.

Return type:

ButtonStyle

property disabled#

Whether the button is disabled or not.

Return type:

bool

await callback(interaction)[source]#

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.

Return type:

str | None

property url#

The URL this button sends you to.

Return type:

str | None

property view#

The underlying view for this item.

Return type:

V | None

PaginatorMenu#

class discord.ext.pages.PaginatorMenu(page_groups, placeholder=None, custom_id=None)[source]#

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

Parameters:
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 channel_types#

A list of channel types that can be selected in this menu.

property custom_id#

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

Return type:

str

property disabled#

Whether the select is disabled or not.

Return type:

bool

property max_values#

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

Return type:

int

property min_values#

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

Return type:

int

property options#

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

property placeholder#

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

Return type:

str | None

property values#

Union[List[str], List[Union[discord.Member, discord.User]], List[discord.Role]], List[Union[discord.Member, discord.User, discord.Role]], List[discord.abc.GuildChannel]]: A list of values that have been selected by the user.

property view#

The underlying view for this item.

Return type:

V | None

await callback(interaction)[source]#

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)[source]#

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.