V2 Discord Modal Builder

A TypeScript-first builder library for Discord's experimental V2 Modals and components.
It provides strongly typed, chainable builders for creating full-screen modals with labels, text inputs, select menus, file uploads, and more — with zero raw JSON hassle.

🔗 Reference: Discord Developer Docs – Components
🔗 Support/Hangout Discord: Golden Development
🔗 My YouTube Channel: Golden Development
🔗 My Discord Bot: Golden Bot

✨ Features

• Build Discord V2 Modals with full type safety
• Chainable, ergonomic API matching Discord's new structural standards
• Label (type 18) wrapper component support
• Works seamlessly with discord.js, raw REST, or any interaction framework
• Outputs valid Discord API payloads instantly

🧱 Included Builders

| Component | Builder Class | Description | |---|---|---| | Modal | V2ModalBuilder | Define custom_id, title, and up to 5 top-level child components. | | Label Wrapper | V2LabelBuilder | Pairs a label and description with an inner interactive component. | | Text Display | V2TextDisplayBuilder | Render markdown formatted text blocks inside modals. | | Text Input | V2TextInputBuilder | Modal text fields (short/paragraph) for free-form responses. | | String Select | V2StringSelectBuilder | Dropdown menus with up to 25 custom options. | | User Select | V2UserSelectBuilder | Select one or more users from the server dynamically. | | Role Select | V2RoleSelectBuilder | Let users choose one or more server roles. | | Mentionable Select | V2MentionableSelectBuilder | Select users or roles with a unified component. | | Channel Select | V2ChannelSelectBuilder | Choose from specific types of server channels. | | File Upload | V2FileUploadBuilder | Interactive component allowing users to upload files in modals. | | Radio Group | V2RadioGroupBuilder | Select exactly one option from a defined list of radio buttons. | | Checkbox Group | V2CheckboxGroupBuilder | Select one or many options via a grouped list of checkboxes. | | Checkbox | V2CheckboxBuilder | A single interactive checkbox for simple yes/no questions. |

📦 Installation

npm install v2modalbuilder

🚀 Example Usage

import { TextInputStyle } from "discord-api-types/v10";
import {
  V2ModalBuilder,
  V2LabelBuilder,
  V2TextDisplayBuilder,
  V2CheckboxGroupBuilder,
  V2StringSelectBuilder,
  V2TextInputBuilder,
} from "v2modalbuilder";

const modal = new V2ModalBuilder()
  .setCustomId("golden_dev_intake")
  .setTitle("Golden Development Onboarding")
  .setComponents(
    new V2TextDisplayBuilder(
      "### 🚀 Welcome to Golden Development\n" +
      "Fill out this form to start scaling your infrastructure and workflow automation."
    ),
    new V2LabelBuilder()
      .setLabel("Which services do you require?")
      .setDescription("Select all that apply to your project scope.")
      .setComponent(
        new V2CheckboxGroupBuilder()
          .setCustomId("services_required")
          .addOptions(
            { label: "High-Concurrency API & Load Balancing", value: "api_infra" },
            { label: "Workflow Automation (n8n, Monday.com)", value: "workflow_auto" },
            { label: "Custom Discord Bot Infrastructure", value: "discord_bots" }
          )
      ),
    new V2LabelBuilder()
      .setLabel("Project Timeline")
      .setComponent(
        new V2StringSelectBuilder()
          .setCustomId("project_timeline")
          .setPlaceholder("Select an estimated timeline...")
          .addOptions(
            { label: "Immediate (ASAP)", value: "asap", emoji: "🚀" },
            { label: "1-3 Months", value: "short_term", emoji: "📅" },
            { label: "Flexible / Ongoing", value: "flexible", emoji: "🔄" }
          )
      ),
    new V2LabelBuilder()
      .setLabel("Project Details")
      .setDescription("Provide a brief overview of your infrastructure needs.")
      .setComponent(
        new V2TextInputBuilder()
          .setCustomId("project_details")
          .setStyle(TextInputStyle.Paragraph)
          .setMinLength(50)
          .setMaxLength(2000)
          .setPlaceholder("e.g., We need a PostgreSQL-backed queue system to manage heavy API traffic...")
          .setRequired(true)
      )
  );

interaction.showModal(modal.toJSON());