A package that allows your bot of discord.js v13 & v14 to create the new awesome Discord Modals and interact with them.
🔎
Installation
npm install discord-modals
🔮
What is this package for?
Recently, Discord API officialy announced Modal Interactions.
What is that? Modal is a popup of Text Input Components [Example]. It's so cool and useful for many commands that needs arguments. However, discord.js hasn't added it yet. Discord-Modals can be a solution if you want to test or use Modals right now. Supports discord.js v13 and v14. Try it!
✨
Setup
The most recommended is to put this on your main file.
const { Client } = require('discord.js') // Extract the Client class
const client = new Client({ intents: 32767 }) // Create a Client
const discordModals = require('discord-modals') // Define the discord-modals package!
discordModals(client); // discord-modals needs your client in order to interact with modals
client.login('token') // Login with your bot
Important: Don't forget to put
discordModals(client)
, will be essential to receive the Modal Submit Interaction.
❓
How can i use it?
First of all, we need to understand that Modals and Text Input Components are completely different. Modals is a popup that shows the text input components and text input are the components of modals. To understand better, you can explore the Discord API Documentation here.
Modals have:
- A Title.
- A Custom Id.
- Components (Text Input)
Text Input have:
- A Custom Id
- A Style (Short or Paragraph)
- A Label
- A minimum length
- A maximum length
- A value (A prefilled value if there is not text)
- And...a place holder
If you have understood this, you can continue on "Examples" section.
📜
Examples
If you are ready, take this examples.
- First, we are going to create a Modal.
const { Modal } = require('discord-modals') // Modal class
const modal = new Modal() // We create a Modal
.setCustomId('customid')
.setTitle('Test of Discord-Modals!')
.addComponents()
This is a basic structure of a Modal, but something is missing. Yeah! Text Input components.
- We are going to create and add a Text Input Component to the Modal.
const { Modal, TextInputComponent } = require('discord-modals') // Modal and TextInputComponent class
const modal = new Modal() // We create a Modal
.setCustomId('modal-customid')
.setTitle('Test of Discord-Modals!')
.addComponents(
new TextInputComponent() // We create a Text Input Component
.setCustomId('textinput-customid')
.setLabel('Some text Here')
.setStyle('SHORT') //IMPORTANT: Text Input Component Style can be 'SHORT' or 'LONG'
.setMinLength(4)
.setMaxLength(10)
.setPlaceholder('Write a text here')
.setRequired(true) // If it's required or not
);
Yay! We have the full Modal & Text Input Component, but... How can i send/show a Modal?
- We are going to use the
showModal()
method to send the modal in an interaction.
const { Modal, TextInputComponent, showModal } = require('discord-modals') // Now we extract the showModal method
const modal = new Modal() // We create a Modal
.setCustomId('modal-customid')
.setTitle('Test of Discord-Modals!')
.addComponents(
new TextInputComponent() // We create a Text Input Component
.setCustomId('textinput-customid')
.setLabel('Some text Here')
.setStyle('SHORT') //IMPORTANT: Text Input Component Style can be 'SHORT' or 'LONG'
.setMinLength(4)
.setMaxLength(10)
.setPlaceholder('Write a text here')
.setRequired(true) // If it's required or not
);
client.on('interactionCreate', (interaction) => {
// Let's say the interaction will be a Slash Command called 'ping'.
if(interaction.commandName === 'ping'){
showModal(modal, {
client: client, // This method needs the Client to show the Modal through the Discord API.
interaction: interaction // This method needs the Interaction to show the Modal with the Interaction ID & Token.
})
}
})
Congrats! You show the Modal to the Interaction User. Now, how can i receive the Modal Interaction?
📢
Events: Receiving Modal Submit Interaction
- discord-modals integrates to your Client a new event called
modalSubmit
. We are going to use it. - To have access to the responses, just use the
.getTextInputValue()
method with the Custom Id of the Text Input Component.
Recommendation: Put your
modalSubmit
event on your main file or in an Event Handler.
Reply Examples
- Usual Reply:
client.on('modalSubmit', (modal) => {
if(modal.customId === 'modal-customid'){
const firstResponse = modal.getTextInputValue('textinput-customid')
modal.reply('Congrats! Powered by discord-modals.' + `\`\`\`${firstResponse}\`\`\``)
}
})
- Ephemeral Reply:
client.on('modalSubmit', (modal) => {
if(modal.customId === 'modal-customid'){
const firstResponse = modal.getTextInputValue('textinput-customid')
await modal.deferReply({ ephemeral: true })
modal.followUp({ content: 'Congrats! Powered by discord-modals.' + `\`\`\`${firstResponse}\`\`\``, ephemeral: true })
}
})
And you made it! I hope this examples help you :)
📚
Documentation
- Check our documentation here.
🔨
Developers
- 『𝑴𝒂𝒕𝒆𝒐ᵗᵉᵐ』#9999
⛔
Issues/Bugs?
Please report it on our GitHub Repository here to fix it inmmediately.