Skip to content
This repository has been archived by the owner on Aug 30, 2022. It is now read-only.

Latest commit

 

History

History
843 lines (531 loc) · 33.4 KB

DOCS.md

File metadata and controls

843 lines (531 loc) · 33.4 KB
Raw

Discord-Modals is 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

🔮 General

Methods

.init(client)

Initialize the receivements of Modal Submit Interactions.

Parameter Type Description
Client Client The Client to receive the Modal Submit Interaction.

Returns: void

.showModal(modal, { client: Client, interaction: Interaction })

Shows the Modal to the Interaction User.

Parameter Type Description
Modal Modal or JSONModal The Modal to show.
Options#client Client The Client to manipulate the Interaction for show the Modal.
Options#interaction Interaction The Interaction to show the Modal.

Returns: void

🧩 Classes

Modal

Represents a Modal Form to be shown in response to an Interaction.

  • A modal can contain at most 5 Action Rows. Each of them can contain 1 Text Input/Select Menu Component.
new Modal(data);
Properties Methods
.title .setTitle()
.customId .setCustomId()
.components .addComponents()
.setComponents()
.spliceComponents()
.toJSON()

Properties

.title

The Title of the Modal.

Returns: String

.customId

The Custom Id of the Modal.

Returns: String

.components

The Components of the Modal.

Returns: Array<TextInputComponent|SelectMenuComponent>

Methods

.setTitle('modalTitle')

Sets the Title of the Modal. (Max. 45 characters)

Parameter Type Description
ModalTitle String The Title of the Modal.

Returns: Modal

.setCustomId('modalCustomId')

Sets the Custom Id of the Modal. (Max. 100 characters)

Parameter Type Description
ModalCustomId String The Custom Id of the Modal.

Returns: Modal

.addComponents(...components)

Adds the Components of the Modal.

| Parameter | Type | Description | | ------------ | ----------------------------------------- | ------------------------------------------- | ----------------------------------- | | Components | TextInputComponent | SelectMenuComponent | The components to add in the Modal. |

Returns: Modal

.setComponents(...components)

Adds the Components of the Modal.

| Parameter | Type | Description | | ------------ | ----------------------------------------- | ------------------------------------------- | ----------------------------------- | | Components | TextInputComponent | SelectMenuComponent | The components to set in the Modal. |

Returns: Modal

.spliceComponents()

Removes, replaces, and inserts components in the Modal.

Returns: Modal

.toJSON()

Transforms the Modal to a plain object.

Returns: APIModalInteractionResponseCallbackData

TextInputComponent

extends BaseMessageComponent

Represents a Text Input Component of a Modal.

new TextInputComponent(data);
Properties Methods
.customId .setCustomId()
.label .setLabel()
.minLength .setMinLength()
.maxLength .setMaxLength()
.placeholder .setPlaceholder()
.required .setRequired()
.style .setStyle()
.value .setDefaultValue()
.toJSON()

Properties

.customId

The Custom Id of the Text Input Component.

Returns: String

.label

The Label of the Text Input Component.

Returns: String

.minLength

The Minimum Length of the Text Input Component.

Returns: Number

.maxLength

The Maximum Length of the Text Input Component.

Returns: Number

.placeholder

The Placeholder of the Text Input Component.

Returns: String

.required

If the Text Input Component is required.

Returns: Boolean

.style

The Style of the Text Input Component.

Returns: TextInputComponentStyle

.value

The Default/Pre-filled value of the Text Input Component.

Returns: String

Methods

.setCustomId('textinput-customid')

Sets the Custom Id of the Text Input Component. (Max. 100 characters)

Parameter Type Description
TextInputCustomId String The Custom Id of the Text Input Component.

Returns: TextInputComponent

.setLabel('textinput-label')

Sets the Label of the Text Input Component. (Max. 45 characters)

Parameter Type Description
TextInputLabel String The Label of the Text Input Component.

Returns: TextInputComponent

.setMinLength(Number)

Sets the Minimum Length of the Text Input Component. (Between 1 - 4000)

Parameter Type Description
Number Number (Between 1 - 4000) The Number of the Minimum Length of the Text Input Component.

Returns: TextInputComponent

.setMaxLength(Number)

Sets the Maximum Length of the Text Input Component. (Between 1 - 4000)

Parameter Type Description
Number Number (Between 1 - 4000) The Number of the Maximum Length of the Text Input Component.

Returns: TextInputComponent

.setPlaceholder('Text Input Placeholder')

Sets the Placeholder of the Text Input Component. (Max. 100 characters)

Parameter Type Description
TextInputPlaceholder String The Placeholder of the Text Input Component.

Returns: TextInputComponent

.setRequired(Boolean)

Sets a Boolean if the Text Input Component is required. Default: false.

Parameter Type Description
Boolean Boolean The Boolean if the Text Input Component is required.

Returns: TextInputComponent

.setStyle(TextInputStyle)

Sets the Style of the Text Input Component.

Parameter Type Description
TextInputStyle TextInputComponentStyle The Style of the Text Input Component.

Returns: TextInputComponent

.setDefaultValue('Value')

Sets a Default/Pre-filled Value of the Text Input Component. (Max. 4000 characters)

Parameter Type Description
Value String The Default/Pre-filled value of the Text Input Component.

Returns: TextInputComponent

.toJSON()

Transforms the TextInputComponent to a plain object.

Returns: APITextInputComponent

TextInputStyle

Text Value Description
SHORT 1 [Short] A single-line input
LONG 2 [Paragraph] A multi-line input

SelectMenuComponent

extends BaseMessageComponent

Represents a Select Menu Component of a Modal.

new SelectMenuComponent(data);
Properties Methods
.customId .setCustomId()
.placeholder .setPlaceholder()
.minValues .setMinValues()
.maxValues .setMaxValues()
.options .addOptions()
.disabled .setOptions()
.spliceOptions()
.setDisabled()
.toJSON()

Properties

.customId

The Custom Id of the Select Menu Component.

Returns: String

.placeholder

The Placeholder (text when nothing is selected) of the Select Menu Component.

Returns: String

.minValues

Minimum number of selections allowed for the Select Menu Component.

Returns: Number

.maxValues

Maximum number of selections allowed for the Select Menu Component.

Returns: Number

.options

The Options of the Select Menu Component.

Returns: Array<APISelectMenuOption>

.disabled

If the Select Menu Component is disabled.

Returns: Boolean

Methods

.setCustomId('menu-customid')

Sets the Custom Id of the Select Menu Component. (Max. 100 characters)

Parameter Type Description
MenuCustomId String The Custom Id of the Select Menu Component.

Returns: SelectMenuComponent

.setPlaceholder('Menu Placeholder')

Sets the Placeholder of the Select Menu Component. (Max. 150 characters)

Parameter Type Description
MenuPlaceholder String The placeholder of the Select Menu Component.

Returns: SelectMenuComponent

.setMinValues(Number)

Sets the minimum number of selections allowed for the Select Menu Component.

Parameter Type Description
Number Number (Between 1 - 25) Number of selections to be required.

Returns: SelectMenuComponent

.setMaxValues(Number)

Sets the maximum number of selections allowed for the Select Menu Component.

Parameter Type Description
Number Number (Between 1 - 25) Number of selections to be allowed.

Returns: SelectMenuComponent

.addOptions(...options)

Adds options to the Select Menu Component.

Parameter Type Description
Options APISelectMenuOption The options to add.

Returns: SelectMenuComponent

.setOptions(...options)

Sets the options of the Select Menu Component.

Parameter Type Description
Options APISelectMenuOption The options to set.

Returns: SelectMenuComponent

.spliceOptions()

Removes, replaces, and inserts options in the Select Menu Component.

Returns: SelectMenuComponent

.setDisabled(Boolean)

Sets a Boolean if a Select Menu Component will be disabled.

Parameter Type Description
Boolean Boolean If the Select Menu Component will be disabled.

Returns: SelectMenuComponent

.toJSON()

Transforms the Select Menu Component to a plain object.

Returns: APISelectMenuComponent

ModalActionRow

Represents an Action Row in a Modal.

Properties Methods
.type .addComponent()
.components .componentToJSON()
.toJSON()

Properties

.type

The type of the Modal Action Row (1).

Returns: Number

.components

The Text Input/Select Menu Component of this Action Row.

Returns: Array<APITextInputComponent|APISelectMenuComponent>

Methods

.addComponent(component)

Adds a Text Input/Select Menu Component.

Parameter Type Description
Component TextInputComponent / SelectMenuComponent The component to add in the Action Row.

Returns: ModalActionRow

.componentToJSON(component)

Transforms a Text Input/Select Menu Component to a plain object.

Parameter Type Description
Component TextInputComponent / SelectMenuComponent The component to add in the Action Row.

Returns: APITextInputComponent | APISelectMenuComponent

.toJSON()

Transforms the Modal Action Row to a plain object.

Returns: APIModalActionRowComponent<APITextInputComponent|APISelectMenuComponent>

ModalSubmitField

Represents a Field of a Modal Submit Interaction.

Properties Methods
.type
.customId
.value

Properties

.type

The type of the Modal Submit Field (TEXT_INPUT).

Returns: String

.customId

The Custom Id of the Modal Submit Field.

Returns: String

.value

The Value of the Modal Submit Field.

Returns: String

ModalSubmitSelectMenu

Represents a Select Menu Component of a Modal Submit Interaction.

Properties Methods
.type
.customId
.values

Properties

.type

The type of the Select Menu Component (SELECT_MENU).

Returns: String

.customId

The Custom Id of the Select Menu Component.

Returns: String

.values

The Values of the Select Menu Component.

Returns: Array

ModalSubmitInteraction

extends Interaction

Represents a Modal Submit Interaction.

Properties Methods
.customId .getTextInputValue()
.components .getField()
.fields .getSelectMenuValues()
.selectMenus .getSelectMenu()
.id .deferReply()
.applicationId .reply()
.channelId .fetchReply()
.guildId .editReply()
.user .deleteReply()
.member .followUp()
.memberPermissions .update()
.locale .isFromMessage()
.guildLocale .isRepliable()
.message
.version
.webhook
.type

Properties

.customId

The Custom Id of the Modal.

Returns: String

.components

The Action Rows of the modal.

Returns: Map

.fields

The (Fields) Text Input Components of the Modal.

Returns: Map

.selectMenus

The Select Menu Components of the Modal.

Returns: Map

.id

The Id of the Modal Submit Interaction.

Returns: Snowflake

.applicationId

The application's id.

Returns: Snowflake

.channelId

The Id of the Channel this Modal Submit Interaction was sent in.

Returns: Snowflake

.guildId

The Id of the Guild this Modal Submit Interaction was sent in.

Returns: Snowflake

.user

The User which sent this Modal Submit Interaction.

Returns: User

.member

If this Modal Submit Interaction was sent in a Guild, the Member which sent it.

Returns: GuildMember

.memberPermissions

If this Modal Submit Interaction was sent in a Guild, the Member which sent it.

Returns: ?Readonly<Permissions>

.locale

The Locale of the User who invoked this Modal Submit Interaction.

Returns: String (Locale)

.guildLocale

The preferred Locale from the Guild this Modal Submit Interaction was sent in.

Returns: String (Locale)

.message

The Message where the Modal Submit Interaction was invoked, if the Modal was invoked on a Message Component.

Returns: Message

.version

The Version.

Returns: Number

.webhook

An associated Interaction Webhook, can be used to further interact with this Interaction.

Returns: InteractionWebhook

Methods

.getTextInputValue('textinput-customid')

Gets a Text Input Component value.

Parameter Type Description
TextInputCustomId String The Custom Id of the Text Input Component.

Returns: TextInputComponent#value

.getField('textinput-customid')

Gets a Modal Submit Field.

Parameter Type Description
TextInputCustomId String The Custom Id of the Text Input Component.

Returns: ModalSubmitField

.getSelectMenuValues('menu-customid')

Gets the values of a Select Menu Component.

Parameter Type Description
MenuCustomId String The Custom Id of the Select Menu Component.

Returns: ModalSubmitSelectMenu#values

.getSelectMenu('menu-customid')

Gets a Select Menu Component.

Parameter Type Description
MenuCustomId String The Custom Id of the Select Menu Component.

Returns: ModalSubmitSelectMenu

.isFromMessage()

If the Modal Submit Interaction is from a message.

Returns: Boolean

.isRepliable()

If the Modal Submit Interaction is repliable.

Returns: Boolean

❌ Errors

Discord-Modals integrates some errors to avoid issues and respect the structures.

Code Message
INVALID_VERSION This package is only compatible with discord.js v13 and v14.
NO_CLIENT_PROVIDED No Client was provided to interact with modals.
INVALID_CLIENT The provided Client is invalid in this context.
MODAL_REQUIRED No Modal was provided to show.
OPTIONS_REQUIRED No Options were provided.
CLIENT_REQUIRED No Client was provided on the showModal method options.
INTERACTION_REQUIRED No Interaction was provided on the showModal method options.
INVALID_MODAL The provided Modal is invalid in this context.
INVALID_INTERACTION The provided Interaction is invalid in this context.
TEXT_INPUT_CUSTOM_ID TextInputComponent customId must be a string.
TEXT_INPUT_LABEL TextInputComponent label must be a string.
TEXT_INPUT_PLACEHOLDER TextInputComponent placeholder must be a string.
TEXT_INPUT_VALUE TextInputComponent value must be a string.
MODAL_CUSTOM_ID Modal customId must be a string.
MODAL_TITLE Modal title must be a string.
MODAL_INTERACTION_MESSAGE This Modal Submit Interaction does not have a message to update.

🔨 Do you want to contribute to Discord-Modals?

  • Check our GitHub Repository and Report Issues or make a Pull Request to contribute to this awesome project. We are waiting for you!

Powered by Discord-Modals