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
PaginatedMessage
Constructors
constructor
• new PaginatedMessage(«destructured»?
)
Constructor for the PaginatedMessage class
Parameters
Name | Type | Description |
---|---|---|
«destructured» | PaginatedMessageOptions | The 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
Name | Type |
---|---|
content | string |
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
Name | Type | Description |
---|---|---|
action | PaginatedMessageAction | The action to add. |
Returns
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
Name | Type | Description |
---|---|---|
actions | PaginatedMessageAction [] | The actions to add. |
Returns
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
Name | Type | Description |
---|---|---|
builder | MessageBuilder | (builder : MessageBuilder ) => Promise <MessageBuilder > | Either a callback whose first parameter is new MessageBuilder() , or an already constructed MessageBuilder |
Returns
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
Name | Type | Description |
---|---|---|
embed | EmbedBuilder | (builder : EmbedBuilder ) => Promise <EmbedBuilder > | Either a callback whose first parameter is new EmbedBuilder() , or an already constructed EmbedBuilder |
Returns
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
Name | Type | Description |
---|---|---|
embeds | EmbedBuilder [] | (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
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
Name | Type | Description |
---|---|---|
page | PaginatedMessagePage | The page to add. |
Returns
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
Name | Type | Description |
---|---|---|
action | PaginatedMessageAction | The action to add. |
index | number | The index of the page to add the action to. |
Returns
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
Name | Type | Description |
---|---|---|
actions | PaginatedMessageAction [] | The actions to add. |
index | number | The index of the page to add the actions to. |
Returns
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
Name | Type | Description |
---|---|---|
builder | MessageBuilder | (builder : MessageBuilder ) => MessageBuilder | Either a callback whose first parameter is new MessageBuilder() , or an already constructed MessageBuilder |
Returns
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
Name | Type | Description |
---|---|---|
content | string | The content to set. |
Returns
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
Name | Type | Description |
---|---|---|
embed | EmbedBuilder | (embed : EmbedBuilder ) => EmbedBuilder | Either a callback whose first parameter is new EmbedBuilder() , or an already constructed EmbedBuilder |
Returns
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
Name | Type | Description |
---|---|---|
embeds | EmbedBuilder [] | (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
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
Name | Type | Description |
---|---|---|
pages | PaginatedMessagePage [] | The pages to add. |
Returns
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
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:1387
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:1439
applyTemplateEmbed
▸ Private
applyTemplateEmbed(templateEmbed
, pageEmbeds
): undefined
| (APIEmbed
| JSONEncodable
<APIEmbed
>)[]
Parameters
Name | Type |
---|---|
templateEmbed | undefined | (APIEmbed | JSONEncodable <APIEmbed >)[] |
pageEmbeds | undefined | (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
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1124
getAction
▸ Private
getAction(customId
, index
): undefined
| PaginatedMessageAction
Parameters
Name | Type |
---|---|
customId | string |
index | number |
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
Name | Type | Description |
---|---|---|
index | number | The 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
Name | Type | Description |
---|---|---|
actions | PaginatedMessageAction [] | The actions to be loaded. |
messageOrInteraction | Message <boolean > | AnyInteractableInteraction | The message or interaction that triggered this PaginatedMessage. |
targetUser | User | The 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
Name | Type | Description |
---|---|---|
targetUser | User | The user the handler is for. |
channel | DMChannel | PartialDMChannel | NewsChannel | StageChannel | TextChannel | PrivateThreadChannel | PublicThreadChannel <boolean > | VoiceChannel | The channel the handler is running at. |
interaction | PaginatedMessageInteractionUnion | The 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
Name | Type | Description |
---|---|---|
_ | Collection <string , PaginatedMessageInteractionUnion > | - |
reason | PaginatedMessageStopReasons | The 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
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:1221
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:448
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:1495
mergeEmbeds
▸ Private
mergeEmbeds(templateEmbed
, pageEmbeds
): (APIEmbed
| JSONEncodable
<APIEmbed
>)[]
Parameters
Name | Type |
---|---|
templateEmbed | APIEmbed | 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
Name | Type | Description |
---|---|---|
messageOrInteraction | Message <boolean > | AnyInteractableInteraction | The message or interaction that triggered this PaginatedMessage. |
target | User | The user who will be able to interact with the buttons of this PaginatedMessage. |
index | number | The 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
Name | Type |
---|---|
messageOrInteraction | Message <boolean > | AnyInteractableInteraction |
target | User |
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
Name | Type | Description |
---|---|---|
messageOrInteraction | Message <boolean > | AnyInteractableInteraction | 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: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
Name | Type | Description |
---|---|---|
messageOrInteraction | Message <boolean > | AnyInteractableInteraction | The 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? | User | The 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
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
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 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
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
Name | Type | Description |
---|---|---|
emitPartialDMChannelWarning | boolean | The new emitPartialDMChannelWarning to set |
Returns
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
Name | Type | Description |
---|---|---|
idle | number | The number to set the idle to. |
Returns
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
Name | Type | Description |
---|---|---|
index | number | The number to set the index to. |
Returns
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
Name | Type | Description |
---|---|---|
actions | PaginatedMessageAction [] | The actions to set. |
index | number | The index of the page to set the actions to. This is 0-based. |
Returns
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
Name | Type | Description |
---|---|---|
pages | PaginatedMessagePage [] | The pages to set. |
Returns
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
Name | Type | Description |
---|---|---|
newOptions | PaginatedMessageSelectMenuOptionsFunction | The new options generator to set |
Returns
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
Name | Type | Description |
---|---|---|
placeholder | undefined | string | The new placeholder to set |
Returns
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
Name | Type | Description |
---|---|---|
stopPaginatedMessageCustomIds | string [] | The new stopPaginatedMessageCustomIds to set |
Returns
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
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:1189
setUpMessage
▸ Protected
setUpMessage(messageOrInteraction
): Promise
<void
>
Sets up the message.
Parameters
Name | Type | Description |
---|---|---|
messageOrInteraction | Message <boolean > | AnyInteractableInteraction | The 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
Name | Type | Description |
---|---|---|
wrongUserInteractionReply | PaginatedMessageWrongUserInteractionReplyFunction | The new wrongUserInteractionReply to set |
Returns
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
Name | Type | Description |
---|---|---|
page | PaginatedMessagePage | The content to update the page with. |
Returns
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:502
resolveTemplate
▸ Private
Static
resolveTemplate(template?
): BaseMessageOptions
Parameters
Name | Type |
---|---|
template? | BaseMessageOptions | EmbedBuilder |
Returns
Defined in
projects/utilities/packages/discord.js-utilities/src/lib/PaginatedMessages/PaginatedMessage.ts:1730