Discord Components V2 Guide

https://github.com/zarscape/discord.js-v2-components
Admin
A comprehensive guide demonstrating how to use Discord's interactive Components V2 system with...
Tokens:5,333
Snippets:37
Trust Score:6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Full Slash Command with V2 Components

Source: https://github.com/zarscape/discord.js-v2-components/blob/main/README.md

This snippet demonstrates how to build a complex slash command response using Discord.js V2 components. It includes examples of TextDisplay, Separator, Section with thumbnails and buttons, ChannelSelectMenu, MediaGallery, and File components. Ensure you have the necessary configuration and assets.

```javascript
const {
  SlashCommandBuilder,
  MessageFlags,
  TextDisplayBuilder,
  SeparatorBuilder,
  SeparatorSpacingSize,
  ThumbnailBuilder,
  SectionBuilder,
  ChannelSelectMenuBuilder,
  ActionRowBuilder,
  ContainerBuilder,
  MediaGalleryBuilder,
  MediaGalleryItemBuilder,
  ButtonBuilder,
  ButtonStyle,
  FileBuilder,
  AttachmentBuilder
} = require('discord.js');
const path = require('path');
const config = require('../../config/config.json');

module.exports = {
  data: new SlashCommandBuilder()
    .setName('v2-components')
    .setDescription('Demonstrates all V2 components'),
  async execute(interaction, client) {
    const botAvatar = client.user.displayAvatarURL({ extension: 'png', size: 512 });

    const textDisplay = new TextDisplayBuilder().setContent('🔹 TextDisplay example');
    const separator = new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small);

    const sectionThumb = new SectionBuilder()
      .addTextDisplayComponents(
        new TextDisplayBuilder().setContent('📄 **Section Title**'),
        new TextDisplayBuilder().setContent('Description with thumbnail.')
      )
      .setThumbnailAccessory(new ThumbnailBuilder({ media: { url: botAvatar } }));

    const selectMenu = new ActionRowBuilder().addComponents(
      new ChannelSelectMenuBuilder().setCustomId('channel_select').setPlaceholder('Select a channel…')
    );

    const mediaGallery = new MediaGalleryBuilder().addItems(
      new MediaGalleryItemBuilder().setURL('https://example.com/image1.png'),
      new MediaGalleryItemBuilder().setURL('https://example.com/image2.png')
    );

    const sectionButtons = [
      new SectionBuilder().addTextDisplayComponents(new TextDisplayBuilder().setContent('🔗 **Docs**'))
        .setButtonAccessory(new ButtonBuilder().setLabel('Overview').setURL('https://discord.com/developers/docs/components/overview').setStyle(ButtonStyle.Link)),
      new SectionBuilder().addTextDisplayComponents(new TextDisplayBuilder().setContent('📑 **Reference**'))
        .setButtonAccessory(new ButtonBuilder().setLabel('Types').setURL('https://discord.com/developers/docs/components/reference#what-is-a-component-component-types').setStyle(ButtonStyle.Link)),
      new SectionBuilder().addTextDisplayComponents(new TextDisplayBuilder().setContent('🚀 **Getting Started**'))
        .setButtonAccessory(new ButtonBuilder().setLabel('Guide').setURL('https://discord.com/developers/docs/components/using-message-components').setStyle(ButtonStyle.Link))
    ];

    const filePath = path.join(__dirname, '../../assets/embed-export.json');
    const attachment = new AttachmentBuilder(filePath).setName('embed-export.json');
    const fileComponent = new FileBuilder().setURL('attachment://embed-export.json');

    const container = new ContainerBuilder()
      .setAccentColor(parseInt(config.color.replace('#', ''), 16))
      .addMediaGalleryComponents(mediaGallery)
      .addSectionComponents(sectionThumb)
      .addMediaGalleryComponents(new MediaGalleryBuilder().addItems(new MediaGalleryItemBuilder().setURL(botAvatar)))
      .addSectionComponents(...sectionButtons)
      .addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small))
      .addTextDisplayComponents(
        new TextDisplayBuilder().setContent('📝 **Fully composed with Components V2**'),
        new TextDisplayBuilder().setContent('- TextDisplay: static text'),
        new TextDisplayBuilder().setContent('- Section: grouped text/accessories'),
        new TextDisplayBuilder().setContent('- MediaGallery: images'),
        new TextDisplayBuilder().setContent('- Separator: content dividers'),
        new TextDisplayBuilder().setContent('- File: attachments'),
        new TextDisplayBuilder().setContent('- Button: actions/links'),
        new TextDisplayBuilder().setContent('- ChannelSelectMenu: choose channels')
      )
      .addFileComponents(fileComponent);

    await interaction.reply({
      flags: MessageFlags.IsComponentsV2,
      components: [textDisplay, separator, sectionThumb, selectMenu, container],
      files: [attachment]
    });
  }
};
```

--------------------------------

### Compose a Full-Featured Message Layout with ContainerBuilder

Source: https://context7.com/zarscape/discord.js-v2-components/llms.txt

Use ContainerBuilder to assemble various components into a single, structured Discord message. This example requires importing all necessary builders from 'discord.js'.

```javascript
const {
  SlashCommandBuilder,
  MessageFlags,
  ContainerBuilder,
  TextDisplayBuilder,
  SeparatorBuilder,
  SeparatorSpacingSize,
  SectionBuilder,
  ThumbnailBuilder,
  MediaGalleryBuilder,
  MediaGalleryItemBuilder,
  ButtonBuilder,
  ButtonStyle,
  FileBuilder,
  AttachmentBuilder,
  ActionRowBuilder,
  ChannelSelectMenuBuilder,
} = require('discord.js');
const path = require('path');

module.exports = {
  data: new SlashCommandBuilder()
    .setName('v2-components')
    .setDescription('Demonstrates all V2 components'),

  async execute(interaction, client) {
    const botAvatar = client.user.displayAvatarURL({ extension: 'png', size: 512 });

    // --- Individual components ---
    const textDisplay = new TextDisplayBuilder().setContent('🔹 TextDisplay example');
    const separator = new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small);

    const sectionThumb = new SectionBuilder()
      .addTextDisplayComponents(
        new TextDisplayBuilder().setContent('📄 **Section Title**'),
        new TextDisplayBuilder().setContent('Description with thumbnail.')
      )
      .setThumbnailAccessory(new ThumbnailBuilder({ media: { url: botAvatar } }));

    const selectMenu = new ActionRowBuilder().addComponents(
      new ChannelSelectMenuBuilder().setCustomId('channel_select').setPlaceholder('Select a channel…')
    );

    const mediaGallery = new MediaGalleryBuilder().addItems(
      new MediaGalleryItemBuilder().setURL('https://example.com/image1.png'),
      new MediaGalleryItemBuilder().setURL('https://example.com/image2.png')
    );

    const sectionButtons = [
      new SectionBuilder()
        .addTextDisplayComponents(new TextDisplayBuilder().setContent('🔗 **Docs**'))
        .setButtonAccessory(
          new ButtonBuilder().setLabel('Overview').setURL('https://discord.com/developers/docs/components/overview').setStyle(ButtonStyle.Link)
        ),
      new SectionBuilder()
        .addTextDisplayComponents(new TextDisplayBuilder().setContent('📑 **Reference**'))
        .setButtonAccessory(
          new ButtonBuilder().setLabel('Types').setURL('https://discord.com/developers/docs/components/reference').setStyle(ButtonStyle.Link)
        ),
    ];

    const filePath = path.join(__dirname, '../../assets/embed-export.json');
    const attachment = new AttachmentBuilder(filePath).setName('embed-export.json');
    const fileComponent = new FileBuilder().setURL('attachment://embed-export.json');

    // --- Compose everything into one Container ---
    const container = new ContainerBuilder()
      .setAccentColor(0x5865F2)                          // Discord blurple
      .addMediaGalleryComponents(mediaGallery)
      .addSectionComponents(sectionThumb)
      .addSectionComponents(...sectionButtons)
      .addSeparatorComponents(separator)
      .addTextDisplayComponents(
        new TextDisplayBuilder().setContent('📝 **Fully composed with Components V2**'),
        new TextDisplayBuilder().setContent('- TextDisplay, Section, MediaGallery, File, Button, ChannelSelectMenu')
      )
      .addFileComponents(fileComponent);

    // --- Reply with IsComponentsV2 flag ---
    await interaction.reply({
      flags: MessageFlags.IsComponentsV2,
      components: [textDisplay, separator, sectionThumb, selectMenu, container],
      files: [attachment],
    });
    // Result: A fully structured, multi-section Components V2 message
  },
};
```

--------------------------------

### Create a Link Button Component

Source: https://github.com/zarscape/discord.js-v2-components/blob/main/README.md

Use ButtonBuilder to create clickable buttons. This example shows how to create a link button that navigates to a specified URL.

```javascript
const { ButtonBuilder, ButtonStyle } = require('discord.js');
// Link button
const linkButton = new ButtonBuilder()
  .setLabel('Docs')
  .setURL('https://discord.com/developers/docs/components/overview')
  .setStyle(ButtonStyle.Link);
```

--------------------------------

### Create a File Component

Source: https://github.com/zarscape/discord.js-v2-components/blob/main/README.md

Use AttachmentBuilder to prepare a file for attachment and FileBuilder to reference it within a message component. Ensure the file path is correct.

```javascript
const { FileBuilder, AttachmentBuilder } = require('discord.js');
const file = new AttachmentBuilder('./example.json').setName('example.json');
const fileComponent = new FileBuilder().setURL('attachment://example.json');
```

--------------------------------

### Create a Media Gallery Component

Source: https://github.com/zarscape/discord.js-v2-components/blob/main/README.md

Use MediaGalleryBuilder and MediaGalleryItemBuilder to create a carousel of images or videos. Add items by providing their URLs.

```javascript
const { MediaGalleryBuilder, MediaGalleryItemBuilder } = require('discord.js');
const gallery = new MediaGalleryBuilder().addItems(
  new MediaGalleryItemBuilder().setURL('https://example.com/image1.png'),
  new MediaGalleryItemBuilder().setURL('https://example.com/image2.png')
);
```

--------------------------------

### Create Action and Link Buttons with ButtonBuilder

Source: https://context7.com/zarscape/discord.js-v2-components/llms.txt

Use ButtonBuilder to create clickable buttons. Link buttons open URLs, while action buttons trigger interactions via a customId. Ensure necessary imports are included.

```javascript
const { ButtonBuilder, ButtonStyle, ActionRowBuilder, MessageFlags } = require('discord.js');

module.exports = {
  async execute(interaction) {
    // Link button — no customId required
    const docsButton = new ButtonBuilder()
      .setLabel('Discord Docs')
      .setURL('https://discord.com/developers/docs')
      .setStyle(ButtonStyle.Link);

    // Interaction button — requires customId, handled via interactionCreate
    const confirmButton = new ButtonBuilder()
      .setCustomId('confirm_action')
      .setLabel('Confirm')
      .setStyle(ButtonStyle.Success);

    const row = new ActionRowBuilder().addComponents(docsButton, confirmButton);

    await interaction.reply({
      flags: MessageFlags.IsComponentsV2,
      components: [row],
    });
    // Result: A row with a link button and a green confirm button
  },
};
```

--------------------------------

### Create a Thumbnail Component

Source: https://github.com/zarscape/discord.js-v2-components/blob/main/README.md

Use ThumbnailBuilder to add a small image next to section text. Provide the media URL for the image.

```javascript
const { ThumbnailBuilder } = require('discord.js');
const thumbnail = new ThumbnailBuilder({ media: { url: 'https://example.com/avatar.png' } });
```

--------------------------------

### Create a Section Component

Source: https://github.com/zarscape/discord.js-v2-components/blob/main/README.md

Use SectionBuilder to group text components and optionally include a thumbnail. Sections require either a thumbnail or a button.

```javascript
const { SectionBuilder, TextDisplayBuilder, ThumbnailBuilder } = require('discord.js');
const section = new SectionBuilder()
  .addTextDisplayComponents(
    new TextDisplayBuilder().setContent('📄 **Section Title**'),
    new TextDisplayBuilder().setContent('This is a section description.')
  )
  .setThumbnailAccessory(new ThumbnailBuilder({ media: { url: 'https://example.com/image.png' } }));
```

--------------------------------

### Create a TextDisplay Component

Source: https://github.com/zarscape/discord.js-v2-components/blob/main/README.md

Use TextDisplayBuilder to create static text with Markdown formatting. This is useful for displaying formatted text within messages.

```javascript
const { TextDisplayBuilder } = require('discord.js');
const textDisplay = new TextDisplayBuilder().setContent('📝 **This is a TextDisplay component.**');
```

--------------------------------

### Attach and Display Files Inline with FileBuilder and AttachmentBuilder

Source: https://context7.com/zarscape/discord.js-v2-components/llms.txt

Use AttachmentBuilder to prepare a local file for Discord and FileBuilder to reference it as an inline component using the 'attachment://' protocol. The attachment must also be included in the 'files' array of the interaction reply.

```javascript
const { FileBuilder, AttachmentBuilder, MessageFlags } = require('discord.js');
const path = require('path');

module.exports = {
  async execute(interaction) {
    const filePath = path.join(__dirname, '../../assets/report.json');

    // Step 1: Create the attachment from a local file
    const attachment = new AttachmentBuilder(filePath).setName('report.json');

    // Step 2: Reference the attachment as a component
    const fileComponent = new FileBuilder().setURL('attachment://report.json');

    await interaction.reply({
      flags: MessageFlags.IsComponentsV2,
      components: [fileComponent],
      files: [attachment],   // MUST include in the files array
    });
    // Result: The JSON file is shown as a downloadable inline component
  },
};
```

--------------------------------

### Create a Channel Select Menu Component

Source: https://github.com/zarscape/discord.js-v2-components/blob/main/README.md

Use ChannelSelectMenuBuilder to create a dropdown menu for selecting channels. Set a custom ID and a placeholder message.

```javascript
const { ChannelSelectMenuBuilder } = require('discord.js');
const menu = new ChannelSelectMenuBuilder()
  .setCustomId('channel_select_menu')
  .setPlaceholder('Select a channel…');
```

--------------------------------

### Create a Container Component

Source: https://github.com/zarscape/discord.js-v2-components/blob/main/README.md

Use ContainerBuilder to group multiple components together. You can set an accent color and add various component types like TextDisplay and Separator.

```javascript
const { ContainerBuilder, TextDisplayBuilder, SeparatorBuilder, SeparatorSpacingSize } = require('discord.js');
const container = new ContainerBuilder()
  .setAccentColor(0x5865F2)
  .addTextDisplayComponents(new TextDisplayBuilder().setContent('Hello from a container!'))
  .addSeparatorComponents(new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small));
```

--------------------------------

### Render Static Markdown Text with TextDisplayBuilder

Source: https://context7.com/zarscape/discord.js-v2-components/llms.txt

Use TextDisplayBuilder to display static text content with full Markdown support. This is the most basic building block and can be used standalone or nested within other components. Ensure MessageFlags.IsComponentsV2 is included in the reply.

```javascript
const { TextDisplayBuilder, MessageFlags } = require('discord.js');

// Standalone text display in a slash command reply
module.exports = {
  async execute(interaction) {
    const heading = new TextDisplayBuilder().setContent('# Welcome!');
    const body = new TextDisplayBuilder().setContent(
      '**Components V2** lets you build rich messages without embeds.\n- Fast\n- Flexible\n- Mobile-friendly'
    );

    await interaction.reply({
      flags: MessageFlags.IsComponentsV2,
      components: [heading, body],
    });
    // Result: Two text blocks rendered sequentially in the message
  },
};
```

--------------------------------

### Display Media Carousel with MediaGalleryBuilder

Source: https://context7.com/zarscape/discord.js-v2-components/llms.txt

Use MediaGalleryBuilder and MediaGalleryItemBuilder to create a scrollable carousel of images or videos. Each item requires a URL and an optional description. Multiple galleries can be stacked in a ContainerBuilder.

```javascript
const { MediaGalleryBuilder, MediaGalleryItemBuilder, MessageFlags } = require('discord.js');

module.exports = {
  async execute(interaction) {
    const gallery = new MediaGalleryBuilder().addItems(
      new MediaGalleryItemBuilder()
        .setURL('https://example.com/screenshot1.png')
        .setDescription('Feature overview'),   // alt text / caption
      new MediaGalleryItemBuilder()
        .setURL('https://example.com/screenshot2.png')
        .setDescription('Settings panel'),
      new MediaGalleryItemBuilder()
        .setURL('https://example.com/screenshot3.png')
        .setDescription('Mobile view')
    );

    await interaction.reply({
      flags: MessageFlags.IsComponentsV2,
      components: [gallery],
    });
    // Result: A 3-image scrollable gallery rendered inline in the message
  },
};
```

--------------------------------

### Create a Channel Picker with ChannelSelectMenuBuilder

Source: https://context7.com/zarscape/discord.js-v2-components/llms.txt

Use ChannelSelectMenuBuilder to create a dropdown for selecting channels. It must be wrapped in an ActionRowBuilder and requires a customId for interaction handling. You can specify allowed channel types and the number of selections.

```javascript
const { ChannelSelectMenuBuilder, ActionRowBuilder, ChannelType, MessageFlags } = require('discord.js');

module.exports = {
  async execute(interaction) {
    const menu = new ChannelSelectMenuBuilder()
      .setCustomId('target_channel')
      .setPlaceholder('Choose a text channel…')
      .addChannelTypes(ChannelType.GuildText)  // restrict to text channels only
      .setMinValues(1)
      .setMaxValues(3);

    const row = new ActionRowBuilder().addComponents(menu);

    await interaction.reply({
      flags: MessageFlags.IsComponentsV2,
      components: [row],
      ephemeral: true,
    });
    // Result: An ephemeral message with a channel picker dropdown
  },
};

// Handling the selection elsewhere:
client.on('interactionCreate', async (interaction) => {
  if (!interaction.isChannelSelectMenu()) return;
  if (interaction.customId !== 'target_channel') return;

  const selected = interaction.values; // array of channel IDs
  await interaction.reply({ content: `Selected: ${selected.join(', ')}`, ephemeral: true });
});
```

--------------------------------

### Add Visual Dividers with SeparatorBuilder

Source: https://context7.com/zarscape/discord.js-v2-components/llms.txt

Utilize SeparatorBuilder to create horizontal rules or spacing between components. Configure it with a boolean to show a divider line and a SeparatorSpacingSize (Small or Large) for vertical padding. Remember to include MessageFlags.IsComponentsV2 in the reply.

```javascript
const { SeparatorBuilder, SeparatorSpacingSize, TextDisplayBuilder, MessageFlags } = require('discord.js');

module.exports = {
  async execute(interaction) {
    const top = new TextDisplayBuilder().setContent('**Section A**');
    const divider = new SeparatorBuilder()
      .setDivider(true)                          // show a visible horizontal line
      .setSpacing(SeparatorSpacingSize.Large);   // add generous vertical padding

    const bottom = new TextDisplayBuilder().setContent('**Section B**');

    await interaction.reply({
      flags: MessageFlags.IsComponentsV2,
      components: [top, divider, bottom],
    });
    // Result: Two text blocks separated by a visible horizontal rule
  },
};
```

--------------------------------

### Group Text with Accessories using SectionBuilder

Source: https://context7.com/zarscape/discord.js-v2-components/llms.txt

SectionBuilder groups TextDisplayComponents with either a ThumbnailBuilder or a ButtonBuilder accessory. This is useful for creating elements like profile cards or info panels. Ensure MessageFlags.IsComponentsV2 is set for the reply.

```javascript
const { SectionBuilder, TextDisplayBuilder, ThumbnailBuilder, ButtonBuilder, ButtonStyle, MessageFlags } = require('discord.js');

module.exports = {
  async execute(interaction) {
    // Section with a thumbnail accessory
    const profileSection = new SectionBuilder()
      .addTextDisplayComponents(
        new TextDisplayBuilder().setContent('**ZarScape**'),
        new TextDisplayBuilder().setContent('Discord bot developer & guide author.')
      )
      .setThumbnailAccessory(
        new ThumbnailBuilder({ media: { url: 'https://example.com/avatar.png' } })
      );

    // Section with a button accessory
    const linkSection = new SectionBuilder()
      .addTextDisplayComponents(
        new TextDisplayBuilder().setContent('📖 **Read the Docs**')
      )
      .setButtonAccessory(
        new ButtonBuilder()
          .setLabel('Open')
          .setURL('https://discord.com/developers/docs/components/overview')
          .setStyle(ButtonStyle.Link)
      );

    await interaction.reply({
      flags: MessageFlags.IsComponentsV2,
      components: [profileSection, linkSection],
    });
    // Result: Two sections — one with a thumbnail, one with a link button
  },
};
```

--------------------------------

### Display Small Inline Images with ThumbnailBuilder

Source: https://context7.com/zarscape/discord.js-v2-components/llms.txt

ThumbnailBuilder is used to render small images as accessories within a SectionBuilder. It requires a media object with a 'url' property pointing to a publicly accessible image. This component is typically not used standalone.

```javascript
const { ThumbnailBuilder } = require('discord.js');

// Typically used as an accessory, not standalone
const avatar = new ThumbnailBuilder({
  media: { url: 'https://cdn.discordapp.com/avatars/123456789/abcdef.png' },
});

// Pass to a SectionBuilder via .setThumbnailAccessory(avatar)
```

--------------------------------

### Create a Separator Component

Source: https://github.com/zarscape/discord.js-v2-components/blob/main/README.md

Use SeparatorBuilder to add visual dividers between components. You can set whether to display a divider and the spacing size.

```javascript
const { SeparatorBuilder, SeparatorSpacingSize } = require('discord.js');
const separator = new SeparatorBuilder().setDivider(true).setSpacing(SeparatorSpacingSize.Small);
```
Tokens:
Raw