Discord Components V2 Utility

A robust, type-safe utility package for building Discord Message Components using the builder pattern. This package is fully updated to support all Discord Components V2 features.

Installation

npm install utils-components-v2

Supported Components

Layout & Containers

• ActionRowBuilder (Type 1)
• SectionBuilder (Type 9)
• ContainerBuilder (Type 17) - Accent colors, group components
• LabelBuilder (Type 18) - Title/Description for child components

Interactive

• ButtonBuilder (Type 2)
• StringSelectMenuBuilder (Type 3)
• UserSelectMenuBuilder (Type 5)
• RoleSelectMenuBuilder (Type 6)
• MentionableSelectMenuBuilder (Type 7)
• ChannelSelectMenuBuilder (Type 8)
• RadioGroupBuilder (Type 21) - New V2 Radio selection
• CheckboxGroupBuilder (Type 22) - New V2 Multi-checkbox selection
• CheckboxBuilder (Type 23) - Single checkbox
• FileUploadBuilder (Type 19)

Display

• TextDisplayBuilder (Type 10) - Full Markdown support
• ThumbnailBuilder (Type 11)
• MediaGalleryBuilder (Type 12) - Image galleries
• FileBuilder (Type 13) - Embed files/attachments
• SeparatorBuilder (Type 14) - Dividers and spacing

Form

• TextInputBuilder (Type 4)

Usage Examples

Container with Layout (V2)

import { ContainerBuilder, SectionBuilder, TextDisplayBuilder, SeparatorBuilder } from 'discord-components-v2';

const container = new ContainerBuilder()
  .setAccentColor(0x703487)
  .addComponents(
    new TextDisplayBuilder().setContent('# Coyote Encounter'),
    new SeparatorBuilder().setDivider(true),
    new SectionBuilder().addComponents(
        new TextDisplayBuilder().setContent('What would you like to do?')
    )
  );

Radio & Checkbox Groups (V2 Modal)

import { RadioGroupBuilder, CheckboxGroupBuilder, LabelBuilder } from 'discord-components-v2';

// Radio Group wrapped in a Label
const classSelection = new LabelBuilder()
  .setLabel('Choose your class')
  .setComponent(
    new RadioGroupBuilder()
      .setCustomId('class_radio')
      .addOptions(
        { value: 'warrior', label: 'Warrior' },
        { value: 'wizard', label: 'Wizard' }
      )
  );

Modals (V2)

Modals can now contain advanced V2 components like Radio Groups and Checkboxes, often wrapped in Labels.

import { ModalBuilder, LabelBuilder, TextInputBuilder, TextInputStyle } from 'discord-components-v2';

const modal = new ModalBuilder()
  .setCustomId('feedback_modal')
  .setTitle('User Feedback')
  .addComponents(
    new LabelBuilder()
      .setLabel('How was your experience?')
      .setComponent(
        new TextInputBuilder()
          .setCustomId('experience_input')
          .setStyle(TextInputStyle.Paragraph)
          .setRequired(true)
      )
  );

const payload = modal.toJSON();

Important: Using V2 Components in Messages

When using Discord Components V2 (types 9-23, like Section, Container, RadioGroup, etc.) at the root level of a message, you MUST include the MessageFlags.IsComponentsV2 (1 << 15) flag in your message/interaction response flags.

If you don't include this flag, Discord will return a DiscordAPIError[50035]: Invalid Form Body with the message Value of field "type" must be one of (1,), because it defaults to V1 components (which only allow ActionRow at the root).

Example with Discord.js

import { SectionBuilder, TextDisplayBuilder, MessageFlags } from 'utils-components-v2';

const section = new SectionBuilder().addComponents(
    new TextDisplayBuilder().setContent('This is a V2 section!')
);

await interaction.reply({
    components: [section],
    flags: MessageFlags.IsComponentsV2 // Required for V2 components!
});

If you are already using other flags like Ephemeral, you should combine them:

flags: MessageFlags.IsComponentsV2 | 64 // 64 is EPHEMERAL in Discord API

Features

• Zero Dependencies: Lightweight and extremely fast.
• Type-Safe: Detailed TypeScript interfaces for all Discord V2 API objects.
• Fluent API: Builder pattern for readable and maintainable code.
• Full Coverage: Implements all components defined in the Discord Developer Documentation for V2.