V2 Discord Message Component Builders for Discord.js

This repository provides TypeScript builders for crafting Discord Message Components with full type safety, clean structure, and reusable patterns.

It wraps raw Discord API component structures into easy-to-use, chainable builders designed for use in bots, utilities, or frameworks.

🔗 Reference: Discord Developer Docs – Message Components

🧱 Included Builders

Each builder corresponds to a Discord component type, with smart defaults, validation, and clear APIs.

Here is a list of components and their respective builders with examples:

| Component | Builder Class | Description | Example | |---------------------|------------------------------|-------------|---------| | Button | ButtonBuilder | Build styled, interactive buttons with labels, emojis, custom IDs, and URLs. | new ButtonBuilder().setLabel('Click Me').setCustomId('click_button') | | String Select | StringSelectBuilder | Create dropdown menus with up to 25 options using custom labels, values, emojis, etc. | new StringSelectBuilder().addOptions(['Option 1', 'Option 2']) | | User Select | UserSelectBuilder | Allow the user to select one or more users dynamically from the server. | new UserSelectBuilder() | | Role Select | RoleSelectBuilder | Let users select one or more roles from the server. | new RoleSelectBuilder() | | Mentionable Select | MentionableSelectBuilder | Allow the user to select from users or roles. | new MentionableSelectBuilder() | | Channel Select | ChannelSelectBuilder | Let the user select specific types of server channels (text, voice, etc.). | new ChannelSelectBuilder() | | Action Row | ActionRowBuilder | Compose select menus or buttons into Discord action rows. | new ActionRowBuilder().addComponents(button) | | Container | ContainerBuilder | A utility to group multiple components together. | new ContainerBuilder().addComponents([button, selectMenu]) | | Media Gallery | MediaGallery | Utility to bundle media content (images, videos, etc.). | new MediaGallery().addImage('image_url') | | Section/Separator | SectionBuilder, Separator| Display structured sections and dividers between components. | new SectionBuilder().setText('Section Title') | | File & Thumbnail| File, Thumbnail | Attach files or images. | new File().setFile('file_url') | | Text Displays | TextDisplay | Render text blocks inside components. | new TextDisplay().setText('Hello, World!') |

🧱 Modal Builders

Discord modals are interactive pop-ups that allow users to input data or make choices. These modals are often used in interactive systems to gather information from the user without cluttering the main interface.

Here are the available modal types in this library:

| Modal Type | Builder Class | Description | Example | |-----------------------|------------------------------|-------------|---------| | Modal | ModalBuilder | A general-purpose modal for displaying content with user inputs. | new ModalBuilder().setTitle('User Information').addComponents(button, input) | | Text Input Modal | TextInputModalBuilder | A modal that includes one or more text inputs for user data. | new TextInputModalBuilder().setPlaceholder('Enter your name').setLabel('Name') | | Selection Modal | SelectionModalBuilder | A modal with options such as dropdowns or checkboxes for user selection. | new SelectionModalBuilder().setTitle('Choose your preference').addOptions(['Option 1', 'Option 2']) |

Example: ModalBuilder

import { ModalBuilder } from 'valy.components.v2';

const modal = new ModalBuilder()
  .setTitle('User Information')
  .addComponents(
    new ButtonBuilder().setLabel('Submit').setCustomId('submit_button'),
    new TextInputModalBuilder().setLabel('Enter your name').setPlaceholder('Your Name')
  );

• setTitle('User Information'): Set the modal's title.
• addComponents(): Add buttons, text inputs, or other components inside the modal.

Example: TextInputModalBuilder

import { TextInputModalBuilder } from 'valy.components.v2';

const textInputModal = new TextInputModalBuilder()
  .setLabel('Enter your email')
  .setPlaceholder('Your Email Address')
  .setRequired(true);

• setLabel('Enter your email'): Set the label for the input field.
• setPlaceholder('Your Email Address'): Set a placeholder inside the text input.
• setRequired(true): Make the input field mandatory.

Example: SelectionModalBuilder

import { SelectionModalBuilder } from 'valy.components.v2';

const selectionModal = new SelectionModalBuilder()
  .setTitle('Choose your preference')
  .addOptions(['Option 1', 'Option 2', 'Option 3']);

• addOptions(): Add options for the user to choose from.

📦 Installation

To use these builders in your bot or utility project, clone or copy this directory into your project. The builders are framework-agnostic and can work with any method that sends raw Discord payloads (e.g., REST, Interactions API, libraries like discord.js, harmony, etc.).

Example Usage:

import { V2ComponentBuilder, V2TextDisplayBuilder } from 'valy.components.v2';

const components = new V2ComponentBuilder().addComponents([
  new V2TextDisplayBuilder("Testing Message Component"),
]);

sendMessage(components.toJSON());

This shows how to use the V2ComponentBuilder to create components and send them as a message.

🔗 Resources:

• Discord API Reference: Official documentation for Discord's message components.
• Example Bots using Discord.js: A popular library for interacting with Discord's API.