Components V2 Paginator

Looking for a non-cv2 paginator? Go to https://gist.github.com/Soheab/f226fc06a3468af01ea3168c95b30af8

Usage

0. Give this gist a ⭐️ :P
1. Copy and paste the contents above into a file like utils/paginator.py
2. Import ButtonPaginator and subclass it or use it directly anywhere.

Arguments

Argument	Type	Default	Description
pages	str, TextDisplay, Container, File, Section, MediaGallery, list/tuple	Required	Content to paginate. Lists/tuples allow multiple items per page.
per_page=	int	1	Number of pages to show at once. See Per Page.
author_id=	int or None	None	User ID allowed to interact with the paginator. Defaults to everyone.
timeout=	float	180.0	View timeout in seconds.
delete_message_after=	bool	False	Whether to delete the message after the paginator is stopped or timed out.
disable_items_after=	bool	False	Whether to disable all interactive items after the paginator is stopped or timed out.
container=	Container, bool, or None	None	The container to add all pages to. If `True`, a container will be created.
container_accent_color=	Any	None	Accent color for created Container.
add_buttons_to_container=	bool	False	Whether to add buttons to the created container or the last container page.
title=	str or TextDisplay	None	Title for the current chunk of pages, shown above the pages.
description=	str or TextDisplay	None	Description for the current chunk of pages, shown below the title.
convert_str_to_text_display=	bool	False	Whether to convert all `str` pages to `TextDisplay` in the `__init__`. If `False` (default), conversion is done each time a page is sent.

Example

# different for you ofc
from utils.paginator import ButtonPaginator
# or
from utils import paginator
ButtonPaginator = paginator.ButtonPaginator

# Using
# like in a command

# can be a list of strings/components/files/dict
# need to attach a file to a ui.File or ui.MediaGalleryItem? pass both as list/tuples:
# (<Item>, <File>)
# need multiple files? that's supported too! either in the constructor or from format_page as a list/tuple.
pages = ["hello", "world", "foo", discord.File(...), ]
paginator = ButtonPaginator(pages)
await paginator.start(<interaction or messageable (ctx, text channel, etc)>)


# Subclassing (recommended)
# can be used to pass custom stuff or format the page
class TestPaginator(ButtonPaginator[T]):
  # can be async
  def format_page(self, chunk: list[T]):
    # add "TEST" to all string pages
    for page in chunk:
      if isinstance(page, str):
        page += "\n\nTEST"
      elif isinstance(page, discord.ui.TextDisplay):
        page.content += "\n\nTEST"

    return chunk

# using TestPaginator(pages, ...) instead of ButtonPaginator(pages, ...)
await TestPaginator(...).start(<interaction or messageable (ctx, text channel, etc)>)

Per Page

You can change how many pages are shown at once with the per_page argument. This is useful for showing multiple items together, like images in a gallery.

When using per_page, you can use format_page to format the entire chunk at once.

# pages = ["hello", "world", "foo", "bar"]

class MyPaginator(ButtonPaginator[str]):
    # Can be async
    def format_page(self, chunk: list[str]):
        print(chunk) # ["hello", "world"]
        # or [<discord.ui.TextDisplay>, <discord.ui.TextDisplay>] if convert_str_to_text_display is True
    ...

Note: chunk is always a sequence of pages with a length equal to per_page, except for the last chunk, which may be shorter. This applies even if per_page is 1 (the default).

On Stop

You can override the on_stop method to customize what happens when the paginator is stopped. This method is called when the stop button is pressed.

By default, it sends a message saying "Stopped the paginator." AND handles deleting the message or disabling items based on the parameters you set.

class MyPaginator(ButtonPaginator[str]):
    async def on_stop(self, interaction: discord.Interaction) -> None:
        ... # do anything you want here

        # default behavior:
        if not any([self.disable_items_after, self.delete_message_after]):
            await interaction.response.send_message(
                "Stopped the paginator.", ephemeral=True
            )

        await self.timeout_actions(interaction)
        self.stop()

If you choose to override, you can call await self.timeout_actions(interaction) to perform the default timeout actions (deleting the message or disabling items) if wanted. Otherwise, you can implement your own logic.