syntx.js

Modal

The Modal class builds a discord.js modal; a pop-up form with up to 5 text input fields.

JavaScript
const { Modal } = require("syntx.js");

Creating a modal

JavaScript
const modal = new Modal({
  text: "Send feedback",
  id: "feedback-modal",
  options: [
    { id: "message", label: "Your feedback", style: "paragraph", required: true },
  ],
});

Options

OptionTypeRequiredDescription
textstringYesThe modal's title, shown at the top. Truncated to 45 characters.
idstringYesThe customId, read back in client.modal().
optionsField[]Yes (1-5 items)The text input fields shown in the form.

Warning

A modal needs between 1 and 5 fields. Passing an empty options array, or more than 5, throws a SyntxError.

Field definition

FieldTypeRequiredDefaultDescription
idstringYes—The field's customId, read inside the submit handler.
labelstringYes—The field's label. Truncated to 45 characters.
style"short" | "paragraph"Yes—"short" for a single line, "paragraph" for a multi-line box.
requiredbooleanNofalseWhether the field must be filled in.
minnumberNo1Minimum input length, 1–3999.
maxnumberNo4000Maximum input length, up to 4000.
placeholderstringNo—Grey hint text shown when the field is empty.
valuestringNo—Pre-filled text.
JavaScript
const modal = new Modal({
  text: "Create a ticket",
  id: "ticket-modal",
  options: [
    { id: "subject", label: "Subject", style: "short", required: true, max: 100 },
    { id: "details", label: "Details", style: "paragraph", placeholder: "Describe your issue..." },
  ],
});

Note

If min/max is missing or out of range, syntx.js quietly falls back to 1/4000 instead of throwing. The only thing that does throw is min being greater than max.

Showing the modal

A modal isn't sent like a regular message; it's shown in response to an interaction with showModal(). Pair it with a button, select menu, or slash command:

JavaScript
client.interaction({
  id: "open-feedback",
  content: (interaction) => {
    interaction.showModal(modal.build());
  },
});

client.registerInteractions();

Tip

The same interaction.showModal(modal.build()) call works inside a slash command's execute too; modals aren't tied to buttons specifically.

Warning

Only interactions can open a modal. There's no showModal() on a plain text-command Message, so client.command() handlers can't trigger one directly.

Handling the submission

JavaScript
client.modal({
  id: "feedback-modal",
  run: (interaction) => {
    const text = interaction.fields.getTextInputValue("message");
    interaction.reply(`Thanks for the feedback: ${text}`);
  },
});

client.registerInteractions();

See Client for dynamic {placeholder} ids, e.g. id: "ticket-{userId}".

build()

Returns the underlying discord.js ModalBuilder, ready for showModal().