Skip to main content
Version: Next

ModalKit

ModalKit is an enhanced version of the native Discord.js ModalBuilder, designed to simplify the process of creating and handling modal submissions in your Discord bot.

info

CommandKit provides JSX version of ModalKit as an alternative syntax to the standard Discord.js builders. This is not required, but can be useful for those who prefer a more declarative style. See <Modal/> for more details.

Creating and handling modals​

src/commands/modal-example.js
const { ModalKit } = require('commandkit');
const { TextInputBuilder, TextInputStyle, ActionRowBuilder } = require('discord.js');

// Create the modal
const modal = new ModalKit()
  .setCustomId('myModal')
  .setTitle('My Modal');

// Create the text input components
const favoriteColorInput = new TextInputBuilder()
  .setCustomId('favoriteColorInput')
  .setLabel("What's your favorite color?")
  .setStyle(TextInputStyle.Short);

const hobbiesInput = new TextInputBuilder()
  .setCustomId('hobbiesInput')
  .setLabel("What's some of your favorite hobbies?")
  .setStyle(TextInputStyle.Paragraph);

// Create action rows (one input per row)
const firstActionRow = new ActionRowBuilder().addComponents(favoriteColorInput);
const secondActionRow = new ActionRowBuilder().addComponents(hobbiesInput);

// Add inputs to the modal
modal.addComponents(firstActionRow, secondActionRow);

// Show the modal and handle submission
modal.onSubmit((interaction) => {
  const favoriteColor = interaction.fields.getTextInputValue('favoriteColorInput');
  const hobbies = interaction.fields.getTextInputValue('hobbiesInput');

  interaction.reply(`Your favorite color is ${favoriteColor} and your hobbies are: ${hobbies}`);
});
warning

ModalKit requires a custom ID. Always provide one when creating a modal using setCustomId().

ModalKit Options​

Using onSubmit()​

The onSubmit() method requires a handler function and accepts an optional options object:

modal.onSubmit(
  (modalInteraction) => {
    // Handle the modal submission
    modalInteraction.reply('Modal submitted!');
  },
  {
    time: 60000, // Collector duration in ms (default: 24h)
    autoReset: false, // Reset timer on submission
    once: true, // Listen only once (default: true)
    // Additional Discord.js collector options...
  },
);

Available Options​

OptionTypeDefaultDescription
timenumber86400000Duration in milliseconds to listen for submissions
autoResetbooleanfalseWhether to reset the timer on submission
oncebooleantrueListen for only one submission

You can also use any valid Discord.js InteractionCollectorOptions.

Handling Collector End​

Use onEnd() to run code when the collector stops:

modal
  .onSubmit((interaction) => {
    interaction.reply('Modal submitted!');
  })
  .onEnd((collected) => {
    console.log(`Collected ${collected.size} submissions`);
  });

Disposing the Collector​

To manually stop the collector:

modal
  .onSubmit((interaction) => {
    interaction.reply('Modal submitted!');
  })
  .onEnd(() => {
    console.log('Collector ended');
  });

// Stop collecting submissions
modal.dispose();