Quick Start

If you reading this - you probably wanted pagination for your bot, don't worry, we gotchu!

install spud.js (click on codeblock to copy)

npm i spud.js@latest

Import spud.js into your project

const { ButtonPaginationBuilder, MenuPaginationBuilder } = require('spud.js');

Afterwards, we can create a quite simple example pagination

Button Pagination

In button pagination builder, only message/interaction, and embeds are required on a pagination. you can add embeds using .addEmbeds(...). You can also set embeds in button pagination builder using .setEmbeds(...) as you can see from the code example below.

const page1 = new MessageEmbed().setDescription("This is page 1");
const page2 = new MessageEmbed().setDescription("This is page 2");
const pagination = new ButtonPaginationBuilder(message)
.setEmbeds(page1, page2);
pagination.send();

Menu Pagination

In menu pagination builder however, message/interaction, embeds, and labels are required.
you have to set the embed with the label in an options object. add options object with .addOptions(...) or set pagination options with .setOptions(...) as you can see from the example below.

const pagination = new MenuPaginationBuilder(message).setOptions(
{ embed: page1, label: "Page 1" },
{ embed: page2, label: "Page 2" },
{ embed: page3, label: "Page 3" }
);

pagination.send();

These are the previews of the button pagination and menu pagination examples created with the code above.

Easy as that.

Now that we've seen some starter code for button and menu pagination in Spud.js, let's try out some examples of customizing these pagination builders. Both the button and menu pagination builders have some customization options in common, so we will cover those first.

• time - This is the length of time in milliseconds that users are allowed to interact with the pagination. This specifies how long the pagination will remain active before it automatically ends. If not specified, the pagination will remain active until the bot restarts.


• max - This is the maximum amount of time users are allowed to interact with the pagination so that users cannot keep interacting with the pagination open indefinitely.


• filter - This is the filter that determines which user are allowed to interact with the pagination. This allows only the user to control the interaction and prevent unwanted behavior on the pagination. If not specified, the user in message.author can only use the pagination.


• idle - Accepts a boolean value that determines whether the time interval for the pagination should be reset on every user interaction. If set to true, the pagination will remain open as long as there is continuous user interaction.


• content - This is a string value that specifies the message content to be shown in the pagination. It will be displayed outside pagination embeds.

For example, if you want to limit the time, add a message content to the pagination, and enable fast skip in button pagination builder:

const pagination = new ButtonPaginationBuilder(message)
.setEmbeds(page1, page2)
.setContent("This is made with spud.js!")
.setTime(60000) // 60s
.fastSkip(true)

pagination.send();

fastSkip is not supported in menu paginations.

This is a result of the code used in the example above

It's important to keep in mind that the examples shown in this guide only apply to message pagination. This method is not compatible with Discord interactions, such as slash commands. You must enable interaction in the pagination reply option in order to use it with Discord interactions. We'll cover how to do this in more detail later in the guide.
Now that we have completed the quick start guide, you can click on the link below to learn more about button pagination and menu pagination including builders, and more customizations options.

button pagination menu pagination

Help

If you're having trouble understanding something in the documentation, are experiencing any issues or problems, or just need a gentle nudge in the right direction, please don't hesitate to join our official Support Server. Our team and friendly community members are here to help and are happy to provide assistance, answer your questions, and offer support whenever you need it.