Class: PaginatedMessage

discord.js-utilities/src.PaginatedMessage

This is a PaginatedMessage, a utility to paginate messages (usually embeds). You must either use this class directly or extend it.

remark Please note that for PaginatedMessage to work in DMs to your client, you need to add the 'CHANNEL' partial to your client.options.partials. Message based commands can always be used in DMs, whereas Chat Input interactions can only be used in DMs when they are registered globally.

PaginatedMessage uses MessageComponent buttons that perform the specified action when clicked. You can either use your own actions or the PaginatedMessage.defaultActions. PaginatedMessage.defaultActions is also static so you can modify these directly.

PaginatedMessage also uses pages via Messages.

example

const myPaginatedMessage = new PaginatedMessage();
// Once you have an instance of PaginatedMessage you can call various methods on it to add pages to it.
// For more details see each method's documentation.

myPaginatedMessage.addPageEmbed((embed) => {
        embed
            .setColor('#FF0000')
            .setDescription('example description');

        return embed;
});

myPaginatedMessage.addPageBuilder((builder) => {
        const embed = new MessageEmbed()
            .setColor('#FF0000')
            .setDescription('example description');

        return builder
            .setContent('example content')
            .setEmbeds([embed]);
});

myPaginatedMessage.addPageContent('Example');

myPaginatedMessage.run(message)

remark You can also provide a MessageEmbed template. This will be applied to every page. If a page itself has an embed then the two will be merged, with the content of the page's embed taking priority over the template.

Furthermore, if the template has a footer then it will be applied after the page index part of the footer with a space preceding the template. For example, when setting - Powered by Sapphire Framework the resulting footer will be 1/2 - Powered by Sapphire Framework

example

const myPaginatedMessage = new PaginatedMessage({
    template: new MessageEmbed().setColor('#FF0000').setFooter('- Powered by Sapphire framework')
});

remark To utilize actions you can implement IPaginatedMessageAction into a class.

example

class ForwardAction implements IPaginatedMessageAction {
  public id = '▶️';

  public run({ handler }) {
    if (handler.index !== handler.pages.length - 1) ++handler.index;
  }
}

// You can also give the object directly.

const StopAction: IPaginatedMessageAction = {
  customId: 'CustomStopAction',
  run: ({ collector }) => {
    collector.stop();
  }
}

Hierarchy

PaginatedMessage
↳ LazyPaginatedMessage
↳ PaginatedFieldMessageEmbed
↳ PaginatedMessageEmbedFields

Constructors

constructor

• new PaginatedMessage(__namedParameters?)

Constructor for the PaginatedMessage class

Parameters

Name	Type	Description
`__namedParameters`	`PaginatedMessageOptions`	The PaginatedMessageOptions for this instance of the PaginatedMessage class

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:224

Properties

#thisMazeWasNotMeantForYouContent

• Private #thisMazeWasNotMeantForYouContent: Object

The response we send when someone gets into an invalid flow

Type declaration

Name	Type
`content`	`string`

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:119

actions

• actions: Map<string, PaginatedMessageAction>

The actions which are to be used.

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:145

collector

• collector: null | InteractionCollector<MessageComponentInteraction<CacheType>> = null

The collector used for handling component interactions.

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:135

constructor

• constructor: typeof PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1523

embedFooterSeparator

• embedFooterSeparator: string = PaginatedMessage.embedFooterSeparator

Custom separator to show after the page index in the embed footer. PaginatedMessage will automatically add a space ( ) after the given text. You do not have to add it yourself.

default PaginatedMessage.embedFooterSeparator (static property)

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:177

emitPartialDMChannelWarning

• emitPartialDMChannelWarning: boolean = PaginatedMessage.emitPartialDMChannelWarning

Whether to emit the warning about running a PaginatedMessage in a DM channel without the client having the 'CHANNEL' partial.

remark When using message based commands (as opposed to Application Commands) then you will also need to specify the DIRECT_MESSAGE intent for PaginatedMessage to work.

default PaginatedMessage.emitPartialDMChannelWarning (static property)

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:191

hasEmittedMaxPageWarning

• Protected hasEmittedMaxPageWarning: boolean = false

Tracks whether a warning was already emitted for this PaginatedMessage concerning the maximum amount of pages in the {@link SelectMenu}.

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:207

hasEmittedPartialDMChannelWarning

• Protected hasEmittedPartialDMChannelWarning: boolean = false

Tracks whether a warning was already emitted for this PaginatedMessage concerning the PaginatedMessage being called in a DMChannel without the client having the 'Channel' partial.

remark When using message based commands (as opposed to Application Commands) then you will also need to specify the DIRECT_MESSAGE intent for PaginatedMessage to work.

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:216

idle

• idle: number

The amount of milliseconds to idle before the paginator is closed.

default 14.5 minutes

remark This is to ensure it is a bit before interactions expire.

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:157

index

• index: number = 0

The handler's current page/message index.

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:150

messages

• messages: (null | PaginatedMessagePage)[] = []

The pages which were converted from PaginatedMessage.pages

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:140

pageIndexPrefix

• pageIndexPrefix: string = PaginatedMessage.pageIndexPrefix

Custom text to show in front of the page index in the embed footer. PaginatedMessage will automatically add a space ( ) after the given text. You do not have to add it yourself.

default PaginatedMessage.pageIndexPrefix (static property)

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:170

paginatedMessageData

• Protected paginatedMessageData: null | Omit<PaginatedMessageMessageOptionsUnion, "components"> = null

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:195

response

The response message used to edit on page changes.

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:130

selectMenuOptions

• Protected selectMenuOptions: PaginatedMessageSelectMenuOptionsFunction = PaginatedMessage.selectMenuOptions

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:197

selectMenuPlaceholder

• Protected selectMenuPlaceholder: undefined | string = undefined

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:199

stopPaginatedMessageCustomIds

• stopPaginatedMessageCustomIds: string[] = PaginatedMessage.stopPaginatedMessageCustomIds

A list of customId that are bound to actions that will stop the PaginatedMessage

default PaginatedMessage.stopPaginatedMessageCustomIds (static property)

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:183

template

• template: PaginatedMessageMessageOptionsUnion

The template for this PaginatedMessage. You can use templates to set defaults that will apply to each and every page in the PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:163

wrongUserInteractionReply

• Protected wrongUserInteractionReply: PaginatedMessageWrongUserInteractionReplyFunction = PaginatedMessage.wrongUserInteractionReply

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:201

defaultActions

▪ Static defaultActions: PaginatedMessageAction[]

The default actions of this handler.

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1299

deletionStopReasons

▪ Static deletionStopReasons: string[]

The reasons sent by InteractionCollector#end event when the message (or its owner) has been deleted.

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1384

embedFooterSeparator

▪ Static embedFooterSeparator: string = '•'

Custom separator for the page index in the embed footer.

default "•"

remark To overwrite this property change it somewhere in a "setup" file, i.e. where you also call client.login() for your client. Alternatively, you can also customize it on a per-PaginatedMessage basis by passing embedFooterSeparator in the options of the constructor.

example

import { PaginatedMessage } from '@sapphire/discord.js-utilities';

PaginatedMessage.embedFooterSeparator = '|';
// This will make the separator of the embed footer something like "Page 1/2 | Today at 4:20"

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1414

emitPartialDMChannelWarning

▪ Static emitPartialDMChannelWarning: boolean = true

Whether to emit the warning about running a PaginatedMessage in a DM channel without the client the 'CHANNEL' partial.

remark When using message based commands (as opposed to Application Commands) then you will also need to specify the DIRECT_MESSAGE intent for PaginatedMessage to work.

remark To overwrite this property change it somewhere in a "setup" file, i.e. where you also call client.login() for your client. Alternatively, you can also customize it on a per-PaginatedMessage basis by using paginatedMessageInstance.setEmitPartialDMChannelWarning(newBoolean)

default true

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1364

handlers

▪ Static Readonly handlers: Map<string, PaginatedMessage>

The current {@link InteractionCollector} handlers that are active. The key is the ID of of the author who sent the message that triggered this PaginatedMessage

This is to ensure that any given author can only trigger 1 PaginatedMessage. This is important for performance reasons, and users should not have more than 1 PaginatedMessage open at once.

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1432

messages

▪ Static Readonly messages: Map<string, PaginatedMessage>

The messages that are currently being handled by a PaginatedMessage The key is the ID of the message that triggered this PaginatedMessage

This is to ensure that only 1 PaginatedMessage can run on a specified message at once. This is important when having an editable commands solution.

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1423

pageIndexPrefix

▪ Static pageIndexPrefix: string = ''

Custom text to show in front of the page index in the embed footer. PaginatedMessage will automatically add a space ( ) after the given text. You do not have to add it yourself.

default ""

remark To overwrite this property change it somewhere in a "setup" file, i.e. where you also call client.login() for your client.

example

import { PaginatedMessage } from '@sapphire/discord.js-utilities';

PaginatedMessage.pageIndexPrefix = 'Page';
// This will make the footer of the embed something like "Page 1/2"

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1399

selectMenuOptions

▪ Static selectMenuOptions: PaginatedMessageSelectMenuOptionsFunction

A generator for {@link MessageSelectOption} that will be used to generate the options for the {@link MessageSelectMenu}. We do not allow overwriting the {@link MessageSelectOption#value} property with this, as it is vital to how we handle select menu interactions.

param The index of the page to add to the {@link MessageSelectMenu}. We will add 1 to this number because our pages are 0 based, so this will represent the pages as seen by the user.

default

{
    label: `Page ${pageIndex}`
}

remark To overwrite this property change it in a "setup" file prior to calling client.login() for your client.

example

import { PaginatedMessage } from '@sapphire/discord.js-utilities';

PaginatedMessage.selectMenuOptions = (pageIndex) => ({
     label: `Go to page: ${pageIndex}`,
     description: 'This is a description'
});

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1459

stopPaginatedMessageCustomIds

▪ Static stopPaginatedMessageCustomIds: string[]

A list of customId that are bound to actions that will stop the PaginatedMessage

default ['@sapphire/paginated-messages.stop']

remark To overwrite this property change it somewhere in a "setup" file, i.e. where you also call client.login() for your client. Alternatively, you can also customize it on a per-PaginatedMessage basis by using paginatedMessageInstance.setStopPaginatedMessageCustomIds(customIds)

example

import { PaginatedMessage } from '@sapphire/discord.js-utilities';

PaginatedMessage.stopPaginatedMessageCustomIds = ['my-custom-stop-custom-id'];

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1378

wrongUserInteractionReply

▪ Static wrongUserInteractionReply: PaginatedMessageWrongUserInteractionReplyFunction

A generator for {@link MessageComponentInteraction#reply} that will be called and sent whenever an untargeted user interacts with one of the buttons. When modifying this it is recommended that the message is set to be ephemeral so only the user that is pressing the buttons can see them. Furthermore, we also recommend setting allowedMentions: { users: [], roles: [] }, so you don't have to worry about accidentally pinging anyone.

When setting just a string, we will add { ephemeral: true, allowedMentions: { users: [], roles: [] } } for you.

param The {@link User} this PaginatedMessage was intended for.

param The {@link User} that actually clicked the button.

default

{
    content: `Please stop interacting with the components on this message. They are only for ${Formatters.userMention(targetUser.id)}.`,
    ephemeral: true,
    allowedMentions: { users: [], roles: [] }
}

remark To overwrite this property change it in a "setup" file prior to calling client.login() for your client.

example

import { PaginatedMessage } from '@sapphire/discord.js-utilities';

// We  will add ephemeral and no allowed mention for string only overwrites
PaginatedMessage.wrongUserInteractionReply = (targetUser) =>
    `These buttons are only for ${Formatters.userMention(targetUser.id)}. Press them as much as you want, but I won't do anything with your clicks.`;

example

import { PaginatedMessage } from '@sapphire/discord.js-utilities';
import { Formatters } from 'discord.js';

PaginatedMessage.wrongUserInteractionReply = (targetUser) => ({
    content: `These buttons are only for ${Formatters.userMention(
        targetUser.id
    )}. Press them as much as you want, but I won't do anything with your clicks.`,
    ephemeral: true,
    allowedMentions: { users: [], roles: [] }
});

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1503

Methods

addAction

▸ addAction(action): PaginatedMessage

Adds an action to the existing ones. This will be added as the last action.

see PaginatedMessage.setActions for examples on how to structure the action.

Parameters

Name	Type	Description
`action`	`PaginatedMessageAction`	The action to add.

Returns

PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:415

addActions

▸ addActions(actions): PaginatedMessage

Adds actions to the existing ones. The order given is the order they will be used.

see PaginatedMessage.setActions for examples on how to structure the actions.

Parameters

Name	Type	Description
`actions`	`PaginatedMessageAction`[]	The actions to add.

Returns

PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:405

addAsyncPageBuilder

▸ addAsyncPageBuilder(builder): PaginatedMessage

Adds a page to the existing ones asynchronously using a MessageBuilder. This wil be added as the last page.

example

const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const { MessageEmbed } = require('discord.js');

const paginatedMessage = new PaginatedMessage()
    .addAsyncPageBuilder(async (builder) => {
        const someRemoteData = await fetch('https://contoso.com/api/users');

        const embed = new MessageEmbed()
            .setColor('#FF0000')
            .setDescription(someRemoteData.data);

        return builder
            .setContent('example content')
            .setEmbeds([embed]);
});

Parameters

Name	Type	Description
`builder`	`MessageBuilder` \| (`builder`: `MessageBuilder`) => `Promise`<`MessageBuilder`>	Either a callback whose first parameter is `new MessageBuilder()`, or an already constructed MessageBuilder

Returns

PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:542

addAsyncPageEmbed

▸ addAsyncPageEmbed(embed): PaginatedMessage

Adds a page to the existing ones asynchronously using a {@link MessageEmbed}. This wil be added as the last page.

example

const { PaginatedMessage } = require('@sapphire/discord.js-utilities');

const paginatedMessage = new PaginatedMessage()
    .addAsyncPageEmbed(async (embed) => {
        const someRemoteData = await fetch('https://contoso.com/api/users');

        embed
            .setColor('#FF0000')
            .setDescription(someRemoteData.data);

        return embed;
});

Parameters

Name	Type	Description
`embed`	`MessageEmbed` \| (`builder`: `MessageEmbed`) => `Promise`<`MessageEmbed`>	Either a callback whose first parameter is `new MessageEmbed()`, or an already constructed {@link MessageEmbed}

Returns

PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:612

addAsyncPageEmbeds

▸ addAsyncPageEmbeds(embeds): PaginatedMessage

Adds a page to the existing ones using multiple {@link MessageEmbed}'s. This wil be added as the last page.

remark When using this with a callback this will construct 10 {@link MessageEmbed}'s in the callback parameters, regardless of how many are actually used. If this a performance impact you do not want to cope with then it is recommended to use PaginatedMessage.addPageBuilder instead, which will let you add as many embeds as you want, albeit manually

example

const { PaginatedMessage } = require('@sapphire/discord.js-utilities');

const paginatedMessage = new PaginatedMessage().addAsyncPageEmbeds(async (embed0, embed1, embed2) => {
    const someRemoteData = (await fetch('https://contoso.com/api/users')) as any;

    for (const [index, user] of Object.entries(someRemoteData.users.slice(0, 10)) as [`${0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10}`, any][]) {
        switch (index) {
            case '0': {
                embed0.setColor('#FF0000').setDescription('example description 1').setAuthor(user.name);
                break;
            }
            case '1': {
                embed1.setColor('#00FF00').setDescription('example description 2').setAuthor(user.name);
                break;
            }
            case '2': {
                embed2.setColor('#0000FF').setDescription('example description 3').setAuthor(user.name);
                break;
            }
        }
    }

    return [embed0, embed1, embed2];
});

example

const { PaginatedMessage } = require('@sapphire/discord.js-utilities');

const embed1 = new MessageEmbed()
    .setColor('#FF0000')
    .setDescription('example description 1');

const embed2 = new MessageEmbed()
    .setColor('#00FF00')
    .setDescription('example description 2');

const embed3 = new MessageEmbed()
    .setColor('#0000FF')
    .setDescription('example description 3');

const paginatedMessage = new PaginatedMessage()
    .addAsyncPageEmbeds([embed1, embed2, embed3]); // You can add up to 10 embeds

Parameters

Name	Type	Description
`embeds`	`MessageEmbed`[] \| (`embed1`: `MessageEmbed`, `embed2`: `MessageEmbed`, `embed3`: `MessageEmbed`, `embed4`: `MessageEmbed`, `embed5`: `MessageEmbed`, `embed6`: `MessageEmbed`, `embed7`: `MessageEmbed`, `embed8`: `MessageEmbed`, `embed9`: `MessageEmbed`, `embed10`: `MessageEmbed`) => `Promise`<`MessageEmbed`[]>	Either a callback which receives 10 parameters of `new MessageEmbed()`, or an array of already constructed {@link MessageEmbed}'s

Returns

PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:754

addPage

▸ addPage(page): PaginatedMessage

Adds a page to the existing ones. This will be added as the last page.

remark While you can use this method you should first check out PaginatedMessage.addPageBuilder, PaginatedMessage.addPageContent and PaginatedMessage.addPageEmbed as these are easier functional methods of adding pages and will likely already suffice for your needs.

Parameters

Name	Type	Description
`page`	`PaginatedMessagePage`	The page to add.

Returns

PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:457

addPageBuilder

▸ addPageBuilder(builder): PaginatedMessage

Adds a page to the existing ones using a MessageBuilder. This will be added as the last page.

example

const { PaginatedMessage } = require('@sapphire/discord.js-utilities');
const { MessageEmbed } = require('discord.js');

const paginatedMessage = new PaginatedMessage()
    .addPageBuilder((builder) => {
        const embed = new MessageEmbed()
            .setColor('#FF0000')
            .setDescription('example description');

        return builder
            .setContent('example content')
            .setEmbeds([embed]);
});

example

const { MessageEmbed } = require('discord.js');
const { MessageBuilder, PaginatedMessage } = require('@sapphire/discord.js-utilities');

const embed = new MessageEmbed()
    .setColor('#FF0000')
    .setDescription('example description');

const builder = new MessageBuilder()
    .setContent('example content')
    .setEmbeds([embed]);

const paginatedMessage = new PaginatedMessage()
    .addPageBuilder(builder);

Parameters

Name	Type	Description
`builder`	`MessageBuilder` \| (`builder`: `MessageBuilder`) => `MessageBuilder`	Either a callback whose first parameter is `new MessageBuilder()`, or an already constructed MessageBuilder

Returns

PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:516

addPageContent

▸ addPageContent(content): PaginatedMessage

Adds a page to the existing ones using simple message content. This will be added as the last page.

example

const { PaginatedMessage } = require('@sapphire/discord.js-utilities');

const paginatedMessage = new PaginatedMessage()
    .addPageContent('example content');

Parameters

Name	Type	Description
`content`	`string`	The content to set.

Returns

PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:557

addPageEmbed

▸ addPageEmbed(embed): PaginatedMessage

Adds a page to the existing ones using a {@link MessageEmbed}. This wil be added as the last page.

example

const { PaginatedMessage } = require('@sapphire/discord.js-utilities');

const paginatedMessage = new PaginatedMessage()
    .addPageEmbed((embed) => {
        embed
            .setColor('#FF0000')
            .setDescription('example description');

        return embed;
});

example

const { PaginatedMessage } = require('@sapphire/discord.js-utilities');

const embed = new MessageEmbed()
    .setColor('#FF0000')
    .setDescription('example description');

const paginatedMessage = new PaginatedMessage()
    .addPageEmbed(embed);

Parameters

Name	Type	Description
`embed`	`MessageEmbed` \| (`embed`: `MessageEmbed`) => `MessageEmbed`	Either a callback whose first parameter is `new MessageEmbed()`, or an already constructed {@link MessageEmbed}

Returns

PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:589

addPageEmbeds

▸ addPageEmbeds(embeds): PaginatedMessage

Adds a page to the existing ones asynchronously using multiple {@link MessageEmbed}'s. This wil be added as the last page.

example

const { PaginatedMessage } = require('@sapphire/discord.js-utilities');

const paginatedMessage = new PaginatedMessage()
    .addPageEmbeds((embed1, embed2, embed3) => { // You can add up to 10 embeds
        embed1
            .setColor('#FF0000')
            .setDescription('example description 1');

        embed2
            .setColor('#00FF00')
            .setDescription('example description 2');

        embed3
            .setColor('#0000FF')
            .setDescription('example description 3');

        return [embed1, embed2, embed3];
});

example

const { PaginatedMessage } = require('@sapphire/discord.js-utilities');

const embed1 = new MessageEmbed()
    .setColor('#FF0000')
    .setDescription('example description 1');

const embed2 = new MessageEmbed()
    .setColor('#00FF00')
    .setDescription('example description 2');

const embed3 = new MessageEmbed()
    .setColor('#0000FF')
    .setDescription('example description 3');

const paginatedMessage = new PaginatedMessage()
    .addPageEmbeds([embed1, embed2, embed3]); // You can add up to 10 embeds

Parameters

Name	Type	Description
`embeds`	`MessageEmbed`[] \| (`embed1`: `MessageEmbed`, `embed2`: `MessageEmbed`, `embed3`: `MessageEmbed`, `embed4`: `MessageEmbed`, `embed5`: `MessageEmbed`, `embed6`: `MessageEmbed`, `embed7`: `MessageEmbed`, `embed8`: `MessageEmbed`, `embed9`: `MessageEmbed`, `embed10`: `MessageEmbed`) => `MessageEmbed`[]	Either a callback which receives 10 parameters of `new MessageEmbed()`, or an array of already constructed {@link MessageEmbed}'s

Returns

PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:663

addPages

▸ addPages(pages): PaginatedMessage

Add pages to the existing ones. The order given is the order they will be used.

Parameters

Name	Type	Description
`pages`	`PaginatedMessagePage`[]	The pages to add.

Returns

PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:798

applyFooter

▸ Protected applyFooter(message, index): PaginatedMessageMessageOptionsUnion

Applies footer to the last embed of the page

Parameters

Name	Type	Description
`message`	`PaginatedMessageMessageOptionsUnion`	The message options
`index`	`number`	The current index

Returns

PaginatedMessageMessageOptionsUnion

The message options with the footer applied

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1175

applyTemplate

▸ Private applyTemplate(template, options): PaginatedMessageMessageOptionsUnion

Parameters

Name	Type
`template`	`PaginatedMessageMessageOptionsUnion`
`options`	`PaginatedMessageMessageOptionsUnion`

Returns

PaginatedMessageMessageOptionsUnion

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1232

applyTemplateEmbed

▸ Private applyTemplateEmbed(templateEmbed, pageEmbeds): undefined | (MessageEmbed | MessageEmbedOptions | APIEmbed)[]

Parameters

Name	Type
`templateEmbed`	`undefined` \| (`MessageEmbed` \| `MessageEmbedOptions` \| `APIEmbed`)[]
`pageEmbeds`	`undefined` \| (`MessageEmbed` \| `MessageEmbedOptions` \| `APIEmbed`)[]

Clones the current handler into a new instance.

Returns

PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:960

handleCollect

▸ Protected handleCollect(targetUser, channel, interaction): Promise<void>

Handles the collect event from the collector.

Parameters

Name	Type	Description
`targetUser`	`User`	The user the handler is for.
`channel`	`DMChannel` \| `PartialDMChannel` \| `NewsChannel` \| `TextChannel` \| `ThreadChannel`	The channel the handler is running at.
`interaction`	`SelectMenuInteraction`<`CacheType`> \| `ButtonInteraction`<`CacheType`>	The button interaction that was received.

Returns

Promise<void>

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1097

handleEnd

▸ Protected handleEnd(_, reason): void

Handles the end event from the collector.

Parameters

Name	Type	Description
`_`	`Collection`<`string`, `SelectMenuInteraction`<`CacheType`> \| `ButtonInteraction`<`CacheType`>>	-
`reason`	`string`	The reason for which the collector was ended.

Returns

void

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1152

handlePageLoad

▸ Protected handlePageLoad(page, index): Promise<PaginatedMessageMessageOptionsUnion>

Handles the load of a page.

Parameters

Name	Type	Description
`page`	`PaginatedMessagePage`	The page to be loaded.
`index`	`number`	The index of the current page.

Returns

Promise<PaginatedMessageMessageOptionsUnion>

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1077

hasPage

▸ hasPage(index): boolean

Checks whether or not the handler has a specific page.

Parameters

Name	Type	Description
`index`	`number`	The index to check.

Returns

boolean

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:432

mergeArrays

▸ Private mergeArrays<T>(template?, array?): undefined | T[]

Type parameters

Name
`T`

Parameters

Name	Type
`template?`	`T`[]
`array?`	`T`[]

Returns

undefined | T[]

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1284

mergeEmbeds

▸ Private mergeEmbeds(templateEmbed, pageEmbeds): (MessageEmbed | MessageEmbedOptions | APIEmbed)[]

Parameters

Name	Type
`templateEmbed`	`MessageEmbed` \| `MessageEmbedOptions` \| `APIEmbed`
`pageEmbeds`	(`MessageEmbed` \| `MessageEmbedOptions` \| `APIEmbed`)[]

Returns

(MessageEmbed | MessageEmbedOptions | APIEmbed)[]

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1256

resolvePage

▸ resolvePage(index): Promise<PaginatedMessagePage>

Executed whenever an action is triggered and resolved.

Parameters

Name	Type	Description
`index`	`number`	The index to resolve.

Returns

Promise<PaginatedMessagePage>

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:943

resolvePagesOnRun

▸ resolvePagesOnRun(): Promise<void>

Executed whenever PaginatedMessage.run is called.

Returns

Promise<void>

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:933

resolvePaginatedMessageInternationalizationContext

▸ Protected resolvePaginatedMessageInternationalizationContext(messageOrInteraction, targetUser): PaginatedMessageInternationalizationContext

Constructs a PaginatedMessageInternationalizationContext including a deprecation notice for PaginatedMessageInternationalizationContext.author

Parameters

Name	Type	Description
`messageOrInteraction`	`Message`<`boolean`> \| `CommandInteraction`<`CacheType`> \| `ContextMenuInteraction`<`CacheType`> \| `SelectMenuInteraction`<`CacheType`> \| `ButtonInteraction`<`CacheType`>	The message or interaction for which the PaginatedMessageInternationalizationContext should be resolved.
`targetUser`	`User`	The target user for whom this interaction is

Returns

PaginatedMessageInternationalizationContext

A constructed PaginatedMessageInternationalizationContext

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1200

run

▸ run(messageOrInteraction, target?): Promise<PaginatedMessage>

Executes the PaginatedMessage and sends the pages corresponding with PaginatedMessage.index. The handler will start collecting message component interactions.

Parameters

Name	Type	Description
`messageOrInteraction`	`Message`<`boolean`> \| `CommandInteraction`<`CacheType`> \| `ContextMenuInteraction`<`CacheType`> \| `SelectMenuInteraction`<`CacheType`> \| `ButtonInteraction`<`CacheType`>	The message or interaction that triggered this PaginatedMessage. Generally this will be the command message or an interaction (either a {@link CommandInteraction}, a {@link ContextMenuInteraction}, a {@link SelectMenuInteraction} or a {@link ButtonInteraction}), but it can also be another message from your client, i.e. to indicate a loading state.
`target?`	`User`	The user who will be able to interact with the buttons of this PaginatedMessage. If `messageOrInteraction` is an instance of {@link Message} then this defaults to {@link Message.author messageOrInteraction.author}, and if it is an instance of {@link CommandInteraction} then it defaults to {@link CommandInteraction.user messageOrInteraction.user}.

Returns

Promise<PaginatedMessage>

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:821

setActions

▸ setActions(actions, includeDefaultActions?): PaginatedMessage

Clears all current actions and sets them. The order given is the order they will be used.

remark You can retrieve the default actions for the regular pagination

example

const display = new PaginatedMessage();

display.setActions([
  ...PaginatedMessage.defaultActions,
])

remark You can add custom Message Buttons by providing style, customId, type, run and at least one of label or emoji.

example

const display = new PaginatedMessage();

display.setActions([
  {
    style: 'PRIMARY',
    label: 'My Button',
    customId: 'custom_button',
    type: Constants.MessageComponentTypes.BUTTON,
    run: (context) => console.log(context)
  }
], true);

remark You can add custom Message Link Buttons by providing style, url, type, and at least one of label or emoji.

example

const display = new PaginatedMessage();

display.setActions([
  {
    style: 'LINK',
    label: 'Sapphire Website',
    emoji: '🔷',
    url: 'https://sapphirejs.dev',
    type: Constants.MessageComponentTypes.BUTTON
  }
], true);

remark You can add custom Select Menus by providing customId, type, and run.

example

const display = new PaginatedMessage();

display.setActions([
  {
    customId: 'custom_menu',
    type: Constants.MessageComponentTypes.SELECT_MENU,
    run: (context) => console.log(context) // Do something here
  }
], true);

Parameters

Name	Type	Default value	Description
`actions`	`PaginatedMessageAction`[]	`undefined`	The actions to set. This can be either a Button, Link Button, or Select Menu.
`includeDefaultActions`	`boolean`	`false`	Whether to merge in the PaginatedMessage.defaultActions when setting the actions. If you set this to true then you do not need to manually add `...PaginatedMessage.defaultActions` as seen in the first example. The default value is `false` for backwards compatibility within the current major version.

Returns

PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:395

setEmitPartialDMChannelWarning

▸ setEmitPartialDMChannelWarning(emitPartialDMChannelWarning): PaginatedMessage

Sets the PaginatedMessage.emitPartialDMChannelWarning for this instance of PaginatedMessage. This will only apply to this one instance and no others.

Parameters

Name	Type	Description
`emitPartialDMChannelWarning`	`boolean`	The new `emitPartialDMChannelWarning` to set

Returns

PaginatedMessage

The current instance of PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:306

setIdle

▸ setIdle(idle): PaginatedMessage

Sets the amount of time to idle before the paginator is closed.

Parameters

Name	Type	Description
`idle`	`number`	The number to set the idle to.

Returns

PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:324

setIndex

▸ setIndex(index): PaginatedMessage

Sets the handler's current page/message index.

Parameters

Name	Type	Description
`index`	`number`	The number to set the index to.

Returns

PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:315

setPages

▸ setPages(pages): PaginatedMessage

Clears all current pages and messages and sets them. The order given is the order they will be used.

Parameters

Name	Type	Description
`pages`	`PaginatedMessagePage`[]	The pages to set.

Returns

PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:440

setSelectMenuOptions

▸ setSelectMenuOptions(newOptions): PaginatedMessage

Sets the PaginatedMessage.selectMenuOptions for this instance of PaginatedMessage. This will only apply to this one instance and no others.

Parameters

Name	Type	Description
`newOptions`	`PaginatedMessageSelectMenuOptionsFunction`	The new options generator to set

Returns

PaginatedMessage

The current instance of PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:262

setSelectMenuPlaceholder

▸ setSelectMenuPlaceholder(placeholder): PaginatedMessage

Sets the PaginatedMessage.selectMenuPlaceholder for this instance of PaginatedMessage. This will only apply to this one instance and no others.

Parameters

Name	Type	Description
`placeholder`	`undefined` \| `string`	The new placeholder to set

Returns

PaginatedMessage

The current instance of PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:273

setStopPaginatedMessageCustomIds

▸ setStopPaginatedMessageCustomIds(stopPaginatedMessageCustomIds): PaginatedMessage

Sets the PaginatedMessage.stopPaginatedMessageCustomIds for this instance of PaginatedMessage. This will only apply to this one instance and no others.

Parameters

Name	Type	Description
`stopPaginatedMessageCustomIds`	`string`[]	The new `stopPaginatedMessageCustomIds` to set

Returns

PaginatedMessage

The current instance of PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:295

setUpCollector

▸ Protected setUpCollector(channel, targetUser): void

Sets up the message's collector.

Parameters

Name	Type	Description
`channel`	`TextBasedChannel`	The channel the handler is running at.
`targetUser`	`User`	The user the handler is for.

Returns

void

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1044

setUpMessage

▸ Protected setUpMessage(messageOrInteraction, targetUser): Promise<void>

Sets up the message.

Parameters

Name	Type	Description
`messageOrInteraction`	`Message`<`boolean`> \| `CommandInteraction`<`CacheType`> \| `ContextMenuInteraction`<`CacheType`> \| `SelectMenuInteraction`<`CacheType`> \| `ButtonInteraction`<`CacheType`>	The message or interaction that triggered this PaginatedMessage. Generally this will be the command message or an interaction (either a {@link CommandInteraction}, a {@link ContextMenuInteraction}, a {@link SelectMenuInteraction} or a {@link ButtonInteraction}), but it can also be another message from your client, i.e. to indicate a loading state.
`targetUser`	`User`	-

Returns

Promise<void>

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:978

setWrongUserInteractionReply

▸ setWrongUserInteractionReply(wrongUserInteractionReply): PaginatedMessage

Sets the PaginatedMessage.wrongUserInteractionReply for this instance of PaginatedMessage. This will only apply to this one instance and no others.

Parameters

Name	Type	Description
`wrongUserInteractionReply`	`PaginatedMessageWrongUserInteractionReplyFunction`	The new `wrongUserInteractionReply` to set

Returns

PaginatedMessage

The current instance of PaginatedMessage

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:284

resolveTemplate

▸ Static Private resolveTemplate(template?): MessageOptions

Parameters

Name	Type
`template?`	`MessageOptions` \| `MessageEmbed`

Returns

MessageOptions

Defined in

projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1509

Hierarchy​

Constructors​

constructor​

Parameters​

Defined in​

Properties​

#thisMazeWasNotMeantForYouContent​

Type declaration​

Defined in​

actions​

Defined in​

collector​

Defined in​

constructor​

Defined in​

embedFooterSeparator​

Defined in​

emitPartialDMChannelWarning​

Defined in​

hasEmittedMaxPageWarning​

Defined in​

hasEmittedPartialDMChannelWarning​

Defined in​

idle​

Defined in​

index​

Defined in​

messages​

Defined in​

pageIndexPrefix​

Defined in​

pages​

Defined in​

paginatedMessageData​

Defined in​

response​

Defined in​

selectMenuOptions​

Defined in​

selectMenuPlaceholder​

Defined in​

stopPaginatedMessageCustomIds​

Defined in​

template​

Defined in​

wrongUserInteractionReply​

Defined in​

defaultActions​

Defined in​

deletionStopReasons​

Defined in​

embedFooterSeparator​

Defined in​

emitPartialDMChannelWarning​

Defined in​

handlers​

Defined in​

messages​

Defined in​

pageIndexPrefix​

Defined in​

selectMenuOptions​

Defined in​

stopPaginatedMessageCustomIds​

Defined in​

wrongUserInteractionReply​

Defined in​

Methods​

addAction​

Parameters​

Returns​

Defined in​

addActions​

Parameters​

Returns​

Defined in​

addAsyncPageBuilder​

Parameters​

Returns​

Defined in​

Hierarchy

Constructors

constructor

Parameters

Defined in

Properties

#thisMazeWasNotMeantForYouContent

Type declaration

Defined in

actions

Defined in

collector

Defined in

constructor

Defined in

embedFooterSeparator

Defined in

emitPartialDMChannelWarning

Defined in

hasEmittedMaxPageWarning

Defined in

hasEmittedPartialDMChannelWarning

Defined in

idle

Defined in

index

Defined in

messages

Defined in

pageIndexPrefix

Defined in

pages

Defined in

paginatedMessageData

Defined in

response

Defined in

selectMenuOptions

Defined in

selectMenuPlaceholder

Defined in

stopPaginatedMessageCustomIds

Defined in

template

Defined in

wrongUserInteractionReply

Defined in

defaultActions

Defined in

deletionStopReasons

Defined in

embedFooterSeparator

Defined in

emitPartialDMChannelWarning

Defined in

handlers

Defined in

messages

Defined in

pageIndexPrefix

Defined in

selectMenuOptions

Defined in

stopPaginatedMessageCustomIds

Defined in

wrongUserInteractionReply

Defined in

Methods

addAction

Parameters

Returns

Defined in

addActions

Parameters

Returns

Defined in

addAsyncPageBuilder

Parameters

Returns

Defined in