discord.ext.pages – An extension module to provide useful pagination options

New in version 2.0.

This module provides an easy pagination system with buttons.

Example usage in a cog:

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


class PageTest(commands.Cog):
    def __init__(self, bot):
        self.bot = bot

        self.pages = [
            "Page One",  # string (text)
            discord.Embed(title="Page Two"),  # rich embed
            discord.Embed(title="Page Three"),  # another rich embed
        ]
        self.pages[1].set_image(url="https://c.tenor.com/pPKOYQpTO8AAAAAM/monkey-developer.gif")
        self.pages[2].add_field(name="Example Field", value="Example Value", inline=False)
        self.pages[2].add_field(name="Another Example Field", value="Another Example Value", inline=False)

    def get_pages(self):
        return self.pages

    @slash_command(name="pagetest")
    async def pagetest(self, ctx):
        await ctx.defer()
        # initializing the paginator
        paginator = pages.Paginator(pages=self.get_pages(), show_disabled=False, show_indicator=True)

        # customising buttons
        paginator.customize_button("next", button_label=">", button_style=discord.ButtonStyle.green)
        paginator.customize_button("prev", button_label="<", button_style=discord.ButtonStyle.green)
        paginator.customize_button("first", button_label="<<", button_style=discord.ButtonStyle.blurple)
        paginator.customize_button("last", button_label=">>", button_style=discord.ButtonStyle.blurple)

        # start paginating
        await paginator.send(ctx, ephemeral=False)

    # using a custom view
    @slash_command(name="pagetest_custom")
    async def pagetest_custom(self, ctx):
        await ctx.defer()
        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(), show_disabled=False, show_indicator=True, custom_view=view)
        await paginator.send(ctx, ephemeral=False)


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

API Reference

Attributes
Methods
class discord.ext.pages.Paginator(pages, show_disabled=True, show_indicator=True, author_check=True, disable_on_timeout=True, custom_view=None, timeout=180.0)

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

Parameters

  • pages (Union[List[str], List[discord.Embed]]) – The list of strings and/or embeds to paginate.

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

  • show_indicator (bool) – Whether to show the page indicator.

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

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

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

Disables all buttons when the view times out.

await goto_page(interaction, page_number=0)

Updates the interaction response message to show the specified page number.

Parameters

  • interaction (discord.Interaction) – The interaction that invoked the paginator.

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

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.

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

customize_button(button_name=None, button_label=None, button_emoji=None, button_style=<ButtonStyle.secondary: 2>)

Allows you to easily customize the various pagination buttons.

Parameters

  • button_name (str) – The name of the button to customize. Must be one of first, prev, next, or last.

  • button_label (str) – The label to display on the button.

  • button_emoji – The emoji to display on the button.

  • button_style (ButtonStyle) – The ButtonStyle to use for the button.

Returns

The button that was customized.

Return type

PaginatorButton

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

await send(messageable, ephemeral=False)

Sends a message with the paginated items.

Parameters

  • messageable (discord.abc.Messageable) – The messageable channel to send to.

  • ephemeral (bool) – Choose whether the message is ephemeral or not. Only works with slash commands.

Returns

The message that was sent with the paginator.

Return type

Union[Message, WebhookMessage]

await respond(interaction, ephemeral=False)

Sends an interaction response or followup with the paginated items.

Parameters

  • interaction (discord.Interaction) – The interaction associated with this response.

  • ephemeral (bool) – Choose whether the message is ephemeral or not.

Returns

The message sent with the paginator.

Return type

Interaction

class discord.ext.pages.PaginatorButton(label, emoji, style, disabled, button_type, paginator)

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, or last.

  • paginator (Paginator) – The paginator class where this button will be used.

await callback(interaction)

This function is a coroutine.

The callback associated with this UI item.

This can be overridden by subclasses.

Parameters

interaction (Interaction) – The interaction that triggered this UI item.