@qkogarashi/pagination

A pagination module for Discord.js v14 and DiscordX that allows you to easily create interactive messages with page navigation.

Features

• 🚀 Support for Discord.js v14 and DiscordX
• 📑 Two pagination types: buttons and dropdown menu
• 🔧 Fully customizable interface
• 🔄 Dynamic page generation
• ⚡ Simple and user-friendly API
• 📦 TypeScript support
• 🆕 Support for Discord.js v2 Components

Installation

npm install @qkogarashi/pagination
# or
yarn add @qkogarashi/pagination
# or
pnpm add @qkogarashi/pagination

Usage

Basic Example with Buttons

import { Pagination, PaginationType } from '@qkogarashi/pagination';
import { EmbedBuilder } from 'discord.js';

// Create embeds for pages
const pages = [
  { embeds: [new EmbedBuilder().setTitle('Page 1').setDescription('Content of page 1')] },
  { embeds: [new EmbedBuilder().setTitle('Page 2').setDescription('Content of page 2')] },
  { embeds: [new EmbedBuilder().setTitle('Page 3').setDescription('Content of page 3')] },
];

// Create pagination with buttons
const pagination = new Pagination(
  interaction, // CommandInteraction, ContextMenuCommandInteraction, MessageComponentInteraction or Message
  pages,
  {
    type: PaginationType.Button, // Pagination type: buttons
    time: 60000, // Timeout in milliseconds (default is 5 minutes)
    enableExit: true, // Enable exit button
    ephemeral: false, // Ephemeral message (only for interactions)
    initialPage: 0, // Initial page (default is 0)
  }
);

// Start pagination
await pagination.start();

Example with Dropdown Menu

import { Pagination, PaginationType } from '@qkogarashi/pagination';
import { EmbedBuilder } from 'discord.js';

// Create embeds for pages
const pages = [
  { embeds: [new EmbedBuilder().setTitle('Page 1').setDescription('Content of page 1')] },
  { embeds: [new EmbedBuilder().setTitle('Page 2').setDescription('Content of page 2')] },
  { embeds: [new EmbedBuilder().setTitle('Page 3').setDescription('Content of page 3')] },
];

// Create pagination with dropdown menu
const pagination = new Pagination(
  interaction,
  pages,
  {
    type: PaginationType.StringSelectMenu, // Pagination type: dropdown menu
    pageText: 'Page {page}', // Text for pages in the menu
    placeholder: 'Select a page', // Placeholder text for the menu
    enableExit: true, // Enable exit option
    labels: {
      start: 'Start',
      end: 'End',
      exit: 'Close',
    },
  }
);

// Start pagination
await pagination.start();

Dynamic Page Generation

import { Pagination, PaginationResolver, PaginationType } from '@qkogarashi/pagination';
import { EmbedBuilder } from 'discord.js';

// Create resolver for dynamic page generation
const resolver = new PaginationResolver(
  async (page) => {
    // Here you can perform asynchronous operations, such as database queries
    return {
      embeds: [
        new EmbedBuilder()
          .setTitle(`Dynamic Page ${page + 1}`)
          .setDescription(`This is a dynamically generated page ${page + 1}`)
      ]
    };
  },
  10 // Total number of pages
);

// Create pagination with dynamic resolver
const pagination = new Pagination(
  interaction,
  resolver,
  {
    type: PaginationType.Button,
    enableExit: true,
  }
);

// Start pagination
await pagination.start();

Using Discord.js v2 Components

import { Pagination, PaginationType } from '@qkogarashi/pagination';
import { ContainerBuilder, SectionBuilder, TextDisplayBuilder } from 'discord.js';

// Create embeds for pages
const pages = [
  { components: [new ContainerBuilder().addSectionComponents(new SectionBuilder().addTextDisplayComponents(new TextDisplayBuilder({ content: `Example — 1` })))] },
  { components: [new ContainerBuilder().addSectionComponents(new SectionBuilder().addTextDisplayComponents(new TextDisplayBuilder({ content: `Example — 2` })))] },
];

// Create pagination with v2 components
const pagination = new Pagination(
  interaction,
  pages,
  {
    type: PaginationType.Button,
    isV2Components: true, // Enable v2 components support
    enableExit: true,
  }
);

// Start pagination
await pagination.start();

API

Pagination Class

The main class for creating pagination.

constructor(
  sendTo: PaginationSendTo,
  pages: PaginationItem[] | PaginationResolver,
  config?: PaginationOptions
)

Parameters:

• sendTo: Where to send the pagination (CommandInteraction, ContextMenuCommandInteraction, MessageComponentInteraction, Message, or TextBasedChannel)
• pages: Array of pages or resolver for dynamic generation
• config: Pagination settings

Methods:

• start(): Starts pagination and sends the message
• getPage(page: number): Gets a page by number

PaginationOptions Interface

Pagination settings.

Common Parameters:

• type: Pagination type (PaginationType.Button or PaginationType.StringSelectMenu)
• time: Timeout in milliseconds (default is 5 minutes)
• enableExit: Enable exit button/option
• ephemeral: Ephemeral message (only for interactions)
• initialPage: Initial page (default is 0)
• showStartEnd: Show start and end buttons/options (default is true)
• onTimeout: Callback function when timeout expires
• debug: Enable debug messages
• isV2Components: Enable Discord.js v2 Components support (default is false)

Button Parameters (PaginationType.Button):

• start: "Start" button settings
• end: "End" button settings
• next: "Next" button settings
• previous: "Previous" button settings
• exit: "Exit" button settings

Dropdown Menu Parameters (PaginationType.StringSelectMenu):

• pageText: Text for pages in the menu
• placeholder: Placeholder text for the menu
• menuId: Custom ID for the menu
• labels: Text settings for "Start", "End", and "Exit" options

License

MIT

Authors

• qKogarashi
• Vijay Meena