Skip to main content

A pagination wrapper for

Project description


An easy-to-use feature-rich pagination wrapper for

Lint Deploy PyPI - Python Version PyPI - Version PePy - Downloads



pip install pygicord

or via git:

pip install git+


It is recommended using the latest stable version of

Getting Started

Basic Paginator

from pygicord import Paginator

def get_pages():
    pages = []
    for i in range(1, 6):
        embed = discord.Embed()
        embed.title = f"Embed no. {i}"
    return pages

async def test(ctx):
    pages = get_pages()
    paginator = Paginator(pages=pages)
    await paginator.start(ctx)


Name Description Type Default
pages A list of objects to paginate or just one. Union[Any, List[Any]]
embed_links Whether to check for Embed Links permission. bool True
timeout The timeout to wait before stopping the pagination session. float 90.0
emojis The custom emojis to use. Mapping[str, str] Discord natives
config The configuration to use. pygicord.Config Config.DEFAULT
force_lock Whether to force adding the lock. bool False
  • emojis attribute is a Mapping of old emoji codes to new emoji codes. Keep reading to understand how to set your custom emojis.
  • force_lock adds a reaction that allows the author of the message to share/unshare the reaction controller to other server members.

Supported emojis formats:

  • Emoji: "🚀" (not recommended)
  • Unicode: "\U0001F680"
  • Unicode name: "\N{ROCKET}"
  • Custom emoji: ":custom_emoji:123456"

Custom Emojis

from pygicord import Paginator

# copy this and replace the values.
custom_emojis = { 
    "\U000023EA": "REPLACE (first page)",
    "\U000025C0": "REPLACE (previous page)",
    "\U000023F9": "REPLACE (stop session)",
    "\U000025B6": "REPLACE (next page)",
    "\U000023E9": "REPLACE (last page)",
    "\U0001F522": "REPLACE (input numbers)",
    "\U0001F512": "REPLACE (lock unlock)",

async def test(ctx):
    paginator = Paginator(pages=pages, emojis=custom_emojis)
    await paginator.start(ctx)


Config.RICH is the only configuration to have the lock set by default. You must set force_lock to True if you want to add it to all other configurations.

Type Controller
Config.DEFAULT first, previous, stop, next, last, input
Config.MINIMAL previous, stop, next
Config.PLAIN first, previous, stop, next, last
Config.RICH first, previous, stop, next, last, input, lock
Control Action
first Jump to first page
previous Go to next page
stop Stop pagination session
next Go to next page
last Jump to last page
input Enter a page number to jump to
input Share/unshare the reaction controller to other server members.
from pygicord import Config, Paginator

async def test(ctx):
    paginator = Paginator(pages=pages, config=Config.MINIMAL)
    await paginator.start(ctx)

Custom Paginator

from pygicord import Paginator, control

class CustomPaginator(Paginator):
    @control(emoji="\N{INFORMATION SOURCE}", position=4.5)
    async def show_info(self, payload):
        """Shows this message."""
        desc = []
        for emoji, control_ in self.controller.items():
            desc.append(f"{emoji}: {control_.callback.__doc__}")
        embed = discord.Embed()
        embed.description = "\n".join(desc)
        embed.set_footer(text="Press any reaction to go back.")
        await self.message.edit(content=None, embed=embed)

pages = [f"Page no. {i}" for i in range(1, 6)]

async def test(ctx):
    paginator = CustomPaginator(pages=pages)
    await paginator.start(ctx)

New Paginator

from pygicord import Base, StopAction, StopPagination, control

class MyPaginator(Base):
    @control(emoji="\N{BLACK SQUARE FOR STOP}", position=2)
    async def stop(self, payload):
        """Stop pagination."""
        raise StopPagination(StopAction.DELETE_MESSAGE)

    def stop_display_if(self):
        """Only displays when pages are atleast 2."""
        return len(self) > 1

    def stop_invoke_if(self, payload):
        """Only the author can stop the session."""
        return == payload.user_id

pages = [f"Page no. {i}" for i in range(1, 6)]

async def test(ctx):
    paginator = MyPaginator(pages=pages)
    await paginator.start(ctx)

You can find more exhaustive examples in the examples folder.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pygicord-1.1.3.tar.gz (11.6 kB view hashes)

Uploaded source

Built Distribution

pygicord-1.1.3-py3-none-any.whl (11.9 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page