Skip to main content

Class: PaginatedMessage

@sapphire/discord.js-utilities.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 defaultActions. 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 EmbedBuilder()
.setColor('#FF0000')
.setDescription('example description');

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

myPaginatedMessage.addPageContent('Example');

myPaginatedMessage.run(message)

Remark

You can also provide a EmbedBuilder 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 EmbedBuilder().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

Constructors

constructor

new PaginatedMessage(«destructured»?)

Constructor for the PaginatedMessage class

Parameters

NameTypeDescription
«destructured»PaginatedMessageOptionsThe PaginatedMessageOptions for this instance of the PaginatedMessage class

Defined in

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

Properties

#thisMazeWasNotMeantForYouContent

Private #thisMazeWasNotMeantForYouContent: Object

The response we send when someone gets into an invalid flow

Type declaration

NameType
contentstring

Defined in

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


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:161


collector

collector: null | InteractionCollector<PaginatedMessageInteractionUnion> = null

The collector used for handling component interactions.

Defined in

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


constructor

constructor: typeof PaginatedMessage

Defined in

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


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:198


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:212


hasEmittedMaxPageWarning

Protected hasEmittedMaxPageWarning: boolean = false

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

Defined in

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


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:237


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:178


index

index: number = 0

The handler's current page/message index.

Defined in

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


messages

messages: (null | PaginatedMessageResolvedPage)[] = []

The pages which were converted from pages

Defined in

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


pageActions

pageActions: (null | Map<string, PaginatedMessageAction>)[] = []

The page-specific actions which are to be used.

Defined in

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


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:191


pages

pages: PaginatedMessagePage[] = []

The pages to be converted to messages

Defined in

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


paginatedMessageData

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

Defined in

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


response

response: null | Message<boolean> | AnyInteractableInteraction = null

The response message used to edit on page changes.

Defined in

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


selectMenuOptions

Protected selectMenuOptions: PaginatedMessageSelectMenuOptionsFunction = PaginatedMessage.selectMenuOptions

Defined in

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


selectMenuPlaceholder

Protected selectMenuPlaceholder: undefined | string = undefined

Defined in

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


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:204


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:184


wrongUserInteractionReply

Protected wrongUserInteractionReply: PaginatedMessageWrongUserInteractionReplyFunction = PaginatedMessage.wrongUserInteractionReply

Defined in

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


defaultActions

Static defaultActions: PaginatedMessageAction[]

The default actions of this handler.

Defined in

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


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:1602


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:1632


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:1582


handlers

Static Readonly handlers: Map<string, PaginatedMessage>

The current 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:1650


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:1641


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:1617


selectMenuOptions

Static selectMenuOptions: PaginatedMessageSelectMenuOptionsFunction

A generator for MessageSelectOption that will be used to generate the options for the StringSelectMenuBuilder. We do not allow overwriting the 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 StringSelectMenuBuilder. 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:1677


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:1596


wrongUserInteractionReply

Static wrongUserInteractionReply: PaginatedMessageWrongUserInteractionReplyFunction

A generator for 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 User this PaginatedMessage was intended for.

Param

The User that actually clicked the button.

Default

import { userMention } from 'discord.js';

{
content: `Please stop interacting with the components on this message. They are only for ${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';
import { userMention } from 'discord.js';

// We will add ephemeral and no allowed mention for string only overwrites
PaginatedMessage.wrongUserInteractionReply = (targetUser) =>
`These buttons are only for ${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 { userMention } from 'discord.js';

PaginatedMessage.wrongUserInteractionReply = (targetUser) => ({
content: `These buttons are only for ${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:1724

Methods

addAction

addAction(action): PaginatedMessage

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

See

setActions for examples on how to structure the action.

Parameters

NameTypeDescription
actionPaginatedMessageActionThe action to add.

Returns

PaginatedMessage

Defined in

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


addActions

addActions(actions): PaginatedMessage

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

See

setActions for examples on how to structure the actions.

Parameters

NameTypeDescription
actionsPaginatedMessageAction[]The actions to add.

Returns

PaginatedMessage

Defined in

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


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 { EmbedBuilder } = require('discord.js');

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

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

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

Parameters

NameTypeDescription
builderMessageBuilder | (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:582


addAsyncPageEmbed

addAsyncPageEmbed(embed): PaginatedMessage

Adds a page to the existing ones asynchronously using a EmbedBuilder. 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

NameTypeDescription
embedEmbedBuilder | (builder: EmbedBuilder) => Promise<EmbedBuilder>Either a callback whose first parameter is new EmbedBuilder(), or an already constructed EmbedBuilder

Returns

PaginatedMessage

Defined in

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


addAsyncPageEmbeds

addAsyncPageEmbeds(embeds): PaginatedMessage

Adds a page to the existing ones using multiple EmbedBuilder's. This wil be added as the last page.

Remark

When using this with a callback this will construct 10 EmbedBuilder'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 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 EmbedBuilder()
.setColor('#FF0000')
.setDescription('example description 1');

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

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

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

Parameters

NameTypeDescription
embedsEmbedBuilder[] | (embed1: EmbedBuilder, embed2: EmbedBuilder, embed3: EmbedBuilder, embed4: EmbedBuilder, embed5: EmbedBuilder, embed6: EmbedBuilder, embed7: EmbedBuilder, embed8: EmbedBuilder, embed9: EmbedBuilder, embed10: EmbedBuilder) => Promise<EmbedBuilder[]>Either a callback which receives 10 parameters of new EmbedBuilder(), or an array of already constructed EmbedBuilder's

Returns

PaginatedMessage

Defined in

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


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 addPageBuilder, addPageContent and addPageEmbed as these are easier functional methods of adding pages and will likely already suffice for your needs.

Parameters

NameTypeDescription
pagePaginatedMessagePageThe page to add.

Returns

PaginatedMessage

Defined in

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


addPageAction

addPageAction(action, index): PaginatedMessage

Add the provided action to a page.

See

setActions for examples on how to structure the action.

Remark

Internally we check if the provided index exists. This means that calling this function before calling any of the methods below this will not work as the amount of pages will always be 0, thus the index will always be out of bounds. That said, make sure you first define your pages and then define your actions for those pages.

Parameters

NameTypeDescription
actionPaginatedMessageActionThe action to add.
indexnumberThe index of the page to add the action to.

Returns

PaginatedMessage

Defined in

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


addPageActions

addPageActions(actions, index): PaginatedMessage

Add the provided actions to a page.

See

setActions for examples on how to structure the actions.

Remark

Internally we check if the provided index exists. This means that calling this function before calling any of the methods below this will not work as the amount of pages will always be 0, thus the index will always be out of bounds. That said, make sure you first define your pages and then define your actions for those pages.

Parameters

NameTypeDescription
actionsPaginatedMessageAction[]The actions to add.
indexnumberThe index of the page to add the actions to.

Returns

PaginatedMessage

Defined in

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


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 { EmbedBuilder } = require('discord.js');

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

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

Example

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

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

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

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

Parameters

NameTypeDescription
builderMessageBuilder | (builder: MessageBuilder) => MessageBuilderEither 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:556


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

NameTypeDescription
contentstringThe content to set.

Returns

PaginatedMessage

Defined in

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


addPageEmbed

addPageEmbed(embed): PaginatedMessage

Adds a page to the existing ones using a EmbedBuilder. 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 EmbedBuilder()
.setColor('#FF0000')
.setDescription('example description');

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

Parameters

NameTypeDescription
embedEmbedBuilder | (embed: EmbedBuilder) => EmbedBuilderEither a callback whose first parameter is new EmbedBuilder(), or an already constructed EmbedBuilder

Returns

PaginatedMessage

Defined in

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


addPageEmbeds

addPageEmbeds(embeds): PaginatedMessage

Adds a page to the existing ones asynchronously using multiple EmbedBuilder's. This wil be added as the last page.

Remark

When using this with a callback this will construct 10 EmbedBuilder'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 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()
.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 EmbedBuilder()
.setColor('#FF0000')
.setDescription('example description 1');

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

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

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

Parameters

NameTypeDescription
embedsEmbedBuilder[] | (embed1: EmbedBuilder, embed2: EmbedBuilder, embed3: EmbedBuilder, embed4: EmbedBuilder, embed5: EmbedBuilder, embed6: EmbedBuilder, embed7: EmbedBuilder, embed8: EmbedBuilder, embed9: EmbedBuilder, embed10: EmbedBuilder) => EmbedBuilder[]Either a callback which receives 10 parameters of new EmbedBuilder(), or an array of already constructed EmbedBuilder's

Returns

PaginatedMessage

Defined in

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


addPages

addPages(pages): PaginatedMessage

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

Parameters

NameTypeDescription
pagesPaginatedMessagePage[]The pages to add.

Returns

PaginatedMessage

Defined in

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


applyFooter

Protected applyFooter(message, index): PaginatedMessageMessageOptionsUnion

Applies footer to the last embed of the page

Parameters

NameTypeDescription
messagePaginatedMessageMessageOptionsUnionThe message options
indexnumberThe current index

Returns

PaginatedMessageMessageOptionsUnion

The message options with the footer applied

Defined in

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


applyTemplate

Private applyTemplate(template, options): PaginatedMessageMessageOptionsUnion

Parameters

NameType
templatePaginatedMessageMessageOptionsUnion
optionsPaginatedMessageMessageOptionsUnion

Returns

PaginatedMessageMessageOptionsUnion

Defined in

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


applyTemplateEmbed

Private applyTemplateEmbed(templateEmbed, pageEmbeds): undefined | (APIEmbed | JSONEncodable<APIEmbed>)[]

Parameters

NameType
templateEmbedundefined | (APIEmbed | JSONEncodable<APIEmbed>)[]
pageEmbedsundefined | (APIEmbed | JSONEncodable<APIEmbed>)[]

Returns

undefined | (APIEmbed | JSONEncodable<APIEmbed>)[]

Defined in

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


clone

clone(): PaginatedMessage

Clones the current handler into a new instance.

Returns

PaginatedMessage

Defined in

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


getAction

Private getAction(customId, index): undefined | PaginatedMessageAction

Parameters

NameType
customIdstring
indexnumber

Returns

undefined | PaginatedMessageAction

Defined in

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


getPageOptions

getPageOptions(index): Promise<undefined | PaginatedMessageMessageOptionsUnion>

Get the options of a page.

Parameters

NameTypeDescription
indexnumberThe index of the page.

Returns

Promise<undefined | PaginatedMessageMessageOptionsUnion>

Defined in

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


handleActionLoad

Protected handleActionLoad(actions, messageOrInteraction, targetUser): Promise<MessageActionRowComponentBuilder[]>

Handles the loading of actions.

Parameters

NameTypeDescription
actionsPaginatedMessageAction[]The actions to be loaded.
messageOrInteractionMessage<boolean> | AnyInteractableInteractionThe message or interaction that triggered this PaginatedMessage.
targetUserUserThe user the handler is for.

Returns

Promise<MessageActionRowComponentBuilder[]>

Defined in

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


handleCollect

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

Handles the collect event from the collector.

Parameters

NameTypeDescription
targetUserUserThe user the handler is for.
channelDMChannel | PartialDMChannel | NewsChannel | StageChannel | TextChannel | PrivateThreadChannel | PublicThreadChannel<boolean> | VoiceChannelThe channel the handler is running at.
interactionPaginatedMessageInteractionUnionThe button interaction that was received.

Returns

Promise<void>

Defined in

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


handleEnd

Protected handleEnd(_, reason): Promise<void>

Handles the end event from the collector.

Parameters

NameTypeDescription
_Collection<string, PaginatedMessageInteractionUnion>-
reasonPaginatedMessageStopReasonsThe reason for which the collector was ended.

Returns

Promise<void>

Defined in

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


handlePageLoad

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

Handles the load of a page.

Parameters

NameTypeDescription
pagePaginatedMessagePageThe page to be loaded.
indexnumberThe index of the current page.

Returns

Promise<PaginatedMessageMessageOptionsUnion>

Defined in

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


hasPage

hasPage(index): boolean

Checks whether or not the handler has a specific page.

Parameters

NameTypeDescription
indexnumberThe index to check.

Returns

boolean

Defined in

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


mergeArrays

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

Type parameters

Name
T

Parameters

NameType
template?T[]
array?T[]

Returns

undefined | T[]

Defined in

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


mergeEmbeds

Private mergeEmbeds(templateEmbed, pageEmbeds): (APIEmbed | JSONEncodable<APIEmbed>)[]

Parameters

NameType
templateEmbedAPIEmbed | JSONEncodable<APIEmbed>
pageEmbeds(APIEmbed | JSONEncodable<APIEmbed>)[]

Returns

(APIEmbed | JSONEncodable<APIEmbed>)[]

Defined in

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


resolvePage

resolvePage(messageOrInteraction, target, index): Promise<PaginatedMessageResolvedPage>

Executed whenever an action is triggered and resolved.

Parameters

NameTypeDescription
messageOrInteractionMessage<boolean> | AnyInteractableInteractionThe message or interaction that triggered this PaginatedMessage.
targetUserThe user who will be able to interact with the buttons of this PaginatedMessage.
indexnumberThe index to resolve.

Returns

Promise<PaginatedMessageResolvedPage>

Defined in

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


resolvePagesOnRun

resolvePagesOnRun(messageOrInteraction, target): Promise<void>

Executed whenever run is called.

Parameters

NameType
messageOrInteractionMessage<boolean> | AnyInteractableInteraction
targetUser

Returns

Promise<void>

Defined in

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


resolvePaginatedMessageInternationalizationContext

Protected resolvePaginatedMessageInternationalizationContext(messageOrInteraction, targetUser): PaginatedMessageInternationalizationContext

Constructs a PaginatedMessageInternationalizationContext

Parameters

NameTypeDescription
messageOrInteractionMessage<boolean> | AnyInteractableInteractionThe message or interaction for which the PaginatedMessageInternationalizationContext should be resolved.
targetUserUserThe 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:1424


run

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

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

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.

Parameters

NameTypeDescription
messageOrInteractionMessage<boolean> | AnyInteractableInteractionThe message or interaction that triggered this PaginatedMessage. Generally this will be the command message or an interaction (either a CommandInteraction, ContextMenuInteraction, or an interaction from PaginatedMessageInteractionUnion), but it can also be another message from your client, i.e. to indicate a loading state.
target?UserThe user who will be able to interact with the buttons of this PaginatedMessage. If messageOrInteraction is an instance of Message then this defaults to Message.author messageOrInteraction.author, and if it is an instance of CommandInteraction then it defaults to CommandInteraction.user messageOrInteraction.user.

Returns

Promise<PaginatedMessage>

Defined in

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


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: ComponentType.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: ComponentType.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: ComponentType.StringSelect,
run: (context) => console.log(context) // Do something here
}
], true);

Parameters

NameTypeDefault valueDescription
actionsPaginatedMessageAction[]undefinedThe actions to set. This can be either a Button, Link Button, or Select Menu.
includeDefaultActionsbooleanfalseWhether to merge in the 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:411


setEmitPartialDMChannelWarning

setEmitPartialDMChannelWarning(emitPartialDMChannelWarning): PaginatedMessage

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

Parameters

NameTypeDescription
emitPartialDMChannelWarningbooleanThe new emitPartialDMChannelWarning to set

Returns

PaginatedMessage

The current instance of PaginatedMessage

Defined in

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


setIdle

setIdle(idle): PaginatedMessage

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

Parameters

NameTypeDescription
idlenumberThe number to set the idle to.

Returns

PaginatedMessage

Defined in

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


setIndex

setIndex(index): PaginatedMessage

Sets the handler's current page/message index.

Parameters

NameTypeDescription
indexnumberThe number to set the index to.

Returns

PaginatedMessage

Defined in

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


setPageActions

setPageActions(actions, index): PaginatedMessage

Clear all actions for a page and set the new ones.

Remark

Internally we check if the provided index exists. This means that calling this function before calling any of the methods below this will not work as the amount of pages will always be 0, thus the index will always be out of bounds. That said, make sure you first define your pages and then define your actions for those pages.

Remark

Add a select menu to the first page, while preserving all default actions:

Example

const display = new PaginatedMessage();

display.setPageActions([
{
customId: 'custom_menu',
type: ComponentType.StringSelect,
run: (context) => console.log(context) // Do something here
}
], 0);

See

setActions for more examples on how to structure the action.

Parameters

NameTypeDescription
actionsPaginatedMessageAction[]The actions to set.
indexnumberThe index of the page to set the actions to. This is 0-based.

Returns

PaginatedMessage

Defined in

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


setPages

setPages(pages): PaginatedMessage

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

Parameters

NameTypeDescription
pagesPaginatedMessagePage[]The pages to set.

Returns

PaginatedMessage

Defined in

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


setSelectMenuOptions

setSelectMenuOptions(newOptions): PaginatedMessage

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

Parameters

NameTypeDescription
newOptionsPaginatedMessageSelectMenuOptionsFunctionThe 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:274


setSelectMenuPlaceholder

setSelectMenuPlaceholder(placeholder): PaginatedMessage

Sets the selectMenuPlaceholder for this instance of PaginatedMessage.

This applies only to the string select menu from the defaultActions that offers "go to page" (we internally check the customId for this)

This will only apply to this one instance and no others.

Parameters

NameTypeDescription
placeholderundefined | stringThe new placeholder to set

Returns

PaginatedMessage

The current instance of PaginatedMessage

Defined in

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


setStopPaginatedMessageCustomIds

setStopPaginatedMessageCustomIds(stopPaginatedMessageCustomIds): PaginatedMessage

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

Parameters

NameTypeDescription
stopPaginatedMessageCustomIdsstring[]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:311


setUpCollector

Protected setUpCollector(channel, targetUser): void

Sets up the message's collector.

Parameters

NameTypeDescription
channelTextBasedChannelThe channel the handler is running at.
targetUserUserThe user the handler is for.

Returns

void

Defined in

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


setUpMessage

Protected setUpMessage(messageOrInteraction): Promise<void>

Sets up the message.

Parameters

NameTypeDescription
messageOrInteractionMessage<boolean> | AnyInteractableInteractionThe message or interaction that triggered this PaginatedMessage. Generally this will be the command message or an interaction (either a CommandInteraction, ContextMenuInteraction, or an interaction from PaginatedMessageInteractionUnion), but it can also be another message from your client, i.e. to indicate a loading state.

Returns

Promise<void>

Defined in

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


setWrongUserInteractionReply

setWrongUserInteractionReply(wrongUserInteractionReply): PaginatedMessage

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

Parameters

NameTypeDescription
wrongUserInteractionReplyPaginatedMessageWrongUserInteractionReplyFunctionThe new wrongUserInteractionReply to set

Returns

PaginatedMessage

The current instance of PaginatedMessage

Defined in

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


updateCurrentPage

updateCurrentPage(page): Promise<PaginatedMessage>

Update the current page.

Remark

This method can only be used after run has been used.

Parameters

NameTypeDescription
pagePaginatedMessagePageThe content to update the page with.

Returns

Promise<PaginatedMessage>

Defined in

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


resolveTemplate

Private Static resolveTemplate(template?): BaseMessageOptions

Parameters

NameType
template?BaseMessageOptions | EmbedBuilder

Returns

BaseMessageOptions

Defined in

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