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

Attributes

• content
• custom_view
• embeds
• files

Methods

• asynccallback
• defupdate_files

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:

• content (str) – The content of the page. Corresponds to the discord.Message.content attribute.

• embeds (Optional[List[Union[List[discord.Embed], discord.Embed]]]) – The embeds of the page. Corresponds to the discord.Message.embeds attribute.

• files (Optional[List[discord.File]]) – A list of local files to be shown with the page.

• custom_view (Optional[discord.ui.View]) – The custom view shown when the page is visible. Overrides the custom_view attribute of the main paginator.

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 discord.File objects so that they can be sent multiple times. This is called internally each time the page is sent.

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

Attributes

• buttons
• current_page
• default_page_group
• get_page_content
• menu
• message
• page_count
• page_groups
• user

Methods

• clsPaginator.from_message
• defadd_button
• defadd_default_buttons
• defadd_item
• defadd_menu
• asynccancel
• defclear_items
• asyncdisable
• defdisable_all_items
• asyncedit
• defenable_all_items
• defget_item
• defget_page_group_content
• asyncgoto_page
• asyncinteraction_check
• defis_dispatching
• defis_finished
• defis_persistent
• asyncon_check_failure
• asyncon_error
• asyncon_timeout
• asyncpage_action
• defremove_button
• defremove_item
• asyncrespond
• asyncsend
• defstop
• asyncupdate
• defupdate_buttons
• defupdate_custom_view
• asyncwait

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, current_page=0)

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.

• current_page (int) – The initial page number to display when updating the paginator.

await on_timeout()

Disables all buttons when the view times out.

Return type:

None

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.

Return type:

None

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.

Return type:

None

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.

Parameters:

button (PaginatorButton) –

remove_button(button_type)

Removes a PaginatorButton from the paginator.

Parameters:

button_type (str) –

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.

Parameters:

custom_view (View) –

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.

Parameters:

page (Page | str | discord.Embed | list[discord.Embed]) –

Return type:

Page

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.

Return type:

None

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.

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, user=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.

• user (Optional[Union[User, Member]]) – If set, changes the user that this paginator belongs to.

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!')

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

Attributes

• custom_id
• disabled
• emoji
• label
• paginator
• sku_id
• style
• url
• view

Methods

• asynccallback

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

Parameters:

• style (discord.ButtonStyle) –

• custom_id (str) –

• row (int) –

property label

The label of the button, if available.

property emoji

The emoji of the button, if available.

property style

The style of the button.

property disabled

Whether the button is disabled or not.

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.

property sku_id

The ID of the SKU this button refers to.

property url

The URL this button sends you to.

property view

The underlying view for this item.

PaginatorMenu

Attributes

• channel_types
• custom_id
• disabled
• max_values
• min_values
• options
• paginator
• placeholder
• values
• view

Methods

• defadd_option
• defappend_option
• asynccallback

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 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.

property disabled

Whether the select is disabled or not.

property max_values

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

property min_values

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

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.

property values

List[str] | List[discord.Member | discord.User]] | List[discord.Role]] | List[discord.Member | discord.User | discord.Role]] | List[discord.abc.GuildChannel] | None: A list of values that have been selected by the user. This will be None if the select has not been interacted with yet.

property view

The underlying view for this item.

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.