Discord-modals NPM

A package that allows your discord.js v13 and v14 bot to create, and interact with Modals, a new Discord feature.

🔎 Installation

npm install discord-modals
yarn add 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. 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'); // Get the Client class
const client = new Client(); // Create a Discord Client, with intents and what you need
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 token

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 (Action Rows with Text Inputs)

Text Inputs 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 placeholder

If you have understood this, you can continue on "Examples" section.

Important: Modals also support select menus. So, you need to know the select menu structure.

📜 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('modal-customid')
	.setTitle('Modal')
	.addComponents();

This is a basic structure of a Modal, but something is missing. Yeah! Components.

We are going to create and add a Text Input Component and a Select Menu to the Modal.

const { Modal, TextInputComponent, SelectMenuComponent } = require('discord-modals'); // Import all

const modal = new Modal() // We create a Modal
	.setCustomId('modal-customid')
	.setTitle('Modal')
	.addComponents(
		new TextInputComponent() // We create a Text Input Component
			.setCustomId('name')
			.setLabel('Name')
			.setStyle('SHORT') //IMPORTANT: Text Input Component Style can be 'SHORT' or 'LONG'
			.setPlaceholder('Write your name here')
			.setRequired(true), // If it's required or not

		new SelectMenuComponent() // We create a Select Menu Component
			.setCustomId('theme')
			.setPlaceholder('What theme of Discord do you like?')
			.addOptions(
				{
					label: 'Dark',
					description: 'The default theme of Discord.',
					value: 'dark',
					emoji: '⚫',
				},
				{
					label: 'Light',
					description: 'Some people hate it, some people like it.',
					value: 'light',
					emoji: '⚪',
				},
			),
	);

Yay! We have the full Modal, 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, SelectMenuComponent, showModal } = require('discord-modals'); // Import all

const modal = new Modal() // We create a Modal
	.setCustomId('modal-customid')
	.setTitle('Modal')
	.addComponents(
		new TextInputComponent() // We create a Text Input Component
			.setCustomId('name')
			.setLabel('Name')
			.setStyle('SHORT') //IMPORTANT: Text Input Component Style can be 'SHORT' or 'LONG'
			.setPlaceholder('Write your name here')
			.setRequired(true), // If it's required or not

		new SelectMenuComponent() // We create a Select Menu Component
			.setCustomId('theme')
			.setPlaceholder('What theme of Discord do you like?')
			.addOptions(
				{
					label: 'Dark',
					description: 'The default theme of Discord.',
					value: 'dark',
					emoji: '⚫',
				},
				{
					label: 'Light',
					description: 'Some people hate it, some people like it.',
					value: 'light',
					emoji: '⚪',
				},
			),
	);

client.on('interactionCreate', (interaction) => {
	// Let's say the interaction will be a Slash Command called 'ping'.
	if (interaction.commandName === 'ping') {
		showModal(modal, {
			client: client, // Client to show the Modal through the Discord API.
			interaction: interaction, // Show the modal with interaction data.
		});
	}
});

Congrats! You show the Modal to the Interaction User. Now, how can i receive the Modal Interaction?

📢 Events: Receiving Modal Submit Interaction and extracting data

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, or if you use Select Menus, the same way, use the .getSelectMenuValues() method with the Custom Id of the Select Menu Component.

Recommendation: Put your modalSubmit event on your main file or in an Event Handler.

client.on('modalSubmit', async (modal) => {
	if (modal.customId === 'modal-customid') {
		const nameResponse = modal.getTextInputValue('name');
		const themeResponse = modal.getSelectMenuValues('theme');
		modal.reply(
			`Thank you for answering the form! Powered by discord-modals.\nSo, you are **${nameResponse}** and you like the **${themeResponse}** theme. Awesome!`,
		);
	}
});

And you made it! I hope this examples help you :)

📚 Documentation

Check our documentation here.

❓ FAQ

Can I show a modal, replying to a modal?

No, Discord API don't support that, but there are plans to add that.

Can I add buttons/select menus to modals?

Yes, but only select menus are supported at this moment. Discord API have plans to add other type of components. Be patient :)

Can I show a modal in a message?

No, modals are only for interactions (Select Menus, Slash Commands, Buttons and Context Menu Commands). They are a response for interactions.

Can I add more than 5 Components in a modal?

No, a modal supports 5 Action Rows (containing 1 Text Input Component or Select Menu per row). There is no plans in Discord API to increase the amount of rows per modal.

DiscordAPIError: Interaction has already been acknowledged.

The showModal() method is a response of an interaction. also reply() or deferReply() are responses of an interaction. If you give a response, you can't give a response again. So you need to remove reply() or editReply() on your code.
If that doesn't work, probably you have the modalSubmit event on the same file of your command, please just add it to a event handler or just separate it.

The Select Menu in Modal is not being displayed in mobile/phone.

Discord is still developing it, so the select menu is not being displayed in this type of clients. For now, only works in desktop/web client. Use it at your own risk.

🔨 Developers

『𝑴𝒂𝒕𝒆𝒐ᵗᵉᵐ』#9999

⛔ Issues/Bugs?

Please report it on our GitHub Repository here to fix it inmmediately or join to the support server.
Credits: This package is based on discord.js, code base was extracted for this.