You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Oct 5, 2025. It is now read-only.
Copy file name to clipboardExpand all lines: guide/additional-info/changes-in-v13.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -75,7 +75,7 @@ In addition to the `interactionCreate` event covered in the above guide, this re
75
75
discord.js now has support for message components!
76
76
This introduces the `MessageActionRow`, `MessageButton`, and `MessageSelectMenu` classes, as well as associated interactions and collectors.
77
77
78
-
Refer to the [message components](/message-components/buttons.md) section of this guide to get started.
78
+
Refer to the [message components](/interactive-components/buttons.md) section of this guide to get started.
79
79
80
80
## Threads
81
81
@@ -1136,7 +1136,7 @@ A Collection of Roles which are managed by the integration.
1136
1136
1137
1137
Provides gateway support for slash command and message component interactions.
1138
1138
1139
-
For more information refer to the [slash commands](/interactions/slash-commands.md#replying-to-slash-commands) and [message components](/message-components/buttons) sections of the guide.
1139
+
For more information refer to the [slash commands](/interactions/slash-commands.md#replying-to-slash-commands) and [message components](/interactive-components/buttons) sections of the guide.
Copy file name to clipboardExpand all lines: guide/interactive-components/buttons.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,7 @@
3
3
The first type of interactive component we'll cover creating is a Button. Buttons are available in a variety of styles and can be used to provide permanent interfaces, temporary confirmation workflows, and other forms of additional interaction with your bot.
4
4
5
5
::: tip
6
-
This page is a follow-up to the [slash commands](/slash-commands/advanced-creation) section and [action rows](/message-components/action-rows) page. Please carefully read those pages first so that you can understand the methods used here.
6
+
This page is a follow-up to the [slash commands](/slash-commands/advanced-creation) section and [action rows](/interactive-components/action-rows) page. Please carefully read those pages first so that you can understand the methods used here.
7
7
:::
8
8
9
9
## Building buttons
@@ -169,4 +169,4 @@ const button = new ButtonBuilder()
169
169
170
170
#### Next steps
171
171
172
-
That's everything you need to know about building and sending buttons! From here you can learn about the other type of message component, [select menus](/message-components/select-menus), or have your bot start listening to [component interactions](/message-components/interactions) from your buttons.
172
+
That's everything you need to know about building and sending buttons! From here you can learn about the other type of message component, [select menus](/interactive-components/select-menus), or have your bot start listening to [component interactions](/interactive-components/interactions) from your buttons.
Copy file name to clipboardExpand all lines: guide/interactive-components/interactions.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,7 @@ Every button click or select menu selection on a component sent by your bot fire
7
7
- Creating a permanent component handler in the <DocsLinkpath="Client:Class#interactionCreate" /> event.
8
8
9
9
::: tip
10
-
This page is a follow-up to the [slash commands](/slash-commands/advanced-creation) section, and assumes you have created either [buttons](/message-components/buttons) or [select menus](/message-components/select-menus) as detailed in this guide. Please carefully read those pages first so that you can understand the methods used here.
10
+
This page is a follow-up to the [slash commands](/slash-commands/advanced-creation) section, and assumes you have created either [buttons](/interactive-components/buttons) or [select menus](/interactive-components/select-menus) as detailed in this guide. Please carefully read those pages first so that you can understand the methods used here.
11
11
:::
12
12
13
13
## Responding to component interactions
@@ -32,7 +32,7 @@ Once `deferUpdate()` has been called, future messages can be sent by calling `fo
32
32
33
33
## Awaiting components
34
34
35
-
If you followed our [buttons](/message-components/buttons) guide, the confirmation workflow for the `ban` command is a good example of a situation where your bot is expecting to receive a single response, from either the Confirm or Cancel button.
35
+
If you followed our [buttons](/interactive-components/buttons) guide, the confirmation workflow for the `ban` command is a good example of a situation where your bot is expecting to receive a single response, from either the Confirm or Cancel button.
36
36
37
37
Begin by adding `withResponse` to the options, and then calling <DocsLinkpath="Message:Class#awaitMessageComponent"type="method" /> on the message. This method returns a [Promise](/additional-info/async-await.md) that resolves when any interaction passes its filter (if one is provided), or throws if none are received before the timeout. If this happens, remove the components and notify the user.
38
38
@@ -82,7 +82,7 @@ try {
82
82
83
83
## Component collectors
84
84
85
-
For situations where you want to collect multiple interactions, the Collector approach is better suited than awaiting singular interactions. Following on from the [select menus](/message-components/select-menus) guide, you're going to extend that example to use an <DocsLinkpath="InteractionCollector:Class"/> to listen for multiple <DocsLinkpath="StringSelectMenuInteraction:Class"/>s.
85
+
For situations where you want to collect multiple interactions, the Collector approach is better suited than awaiting singular interactions. Following on from the [select menus](/interactive-components/select-menus) guide, you're going to extend that example to use an <DocsLinkpath="InteractionCollector:Class"/> to listen for multiple <DocsLinkpath="StringSelectMenuInteraction:Class"/>s.
86
86
87
87
Begin by adding `withResponse` to the options, and then calling <DocsLinkpath="Message:Class#createMessageComponentCollector"type="method" /> on this instance. This method returns an InteractionCollector that will fire its <DocsLinkpath="InteractionCollector:Class#collect" /> event whenever an interaction passes its filter (if one is provided).
Copy file name to clipboardExpand all lines: guide/interactive-components/select-menus.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,7 @@
3
3
Select menus are one of the `MessageComponent` classes, which can be sent via messages or interaction responses.
4
4
5
5
::: tip
6
-
This page is a follow-up to the [slash commands](/slash-commands/advanced-creation.md) section and [action rows](/message-components/action-rows.md) page. Please carefully read those pages first so that you can understand the methods used here.
6
+
This page is a follow-up to the [slash commands](/slash-commands/advanced-creation.md) section and [action rows](/interactive-components/action-rows.md) page. Please carefully read those pages first so that you can understand the methods used here.
Copy file name to clipboardExpand all lines: guide/popular-topics/display-components.md
+21-33Lines changed: 21 additions & 33 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,23 +1,29 @@
1
-
# Components V2
1
+
# Display Components
2
2
3
-
While you might be familiar with [embeds](/popular-topics/embeds.md) in Discord, there are more ways to style and format your messages using **Components V2 (CV2)**, a comprehensive set of layout and content components.
3
+
While you might be familiar with [embeds](/popular-topics/embeds.md) in Discord, there are more ways to style and format your apps messages using **display components**, a comprehensive set of layout and content elements.
4
4
5
-
To use the CV2 components, you need to pass in the `IsComponentsV2` message flag from the <DocsLinkpath="MessageFlags:Enum" /> enum when sending a message. The flag should only be added to the message's `flags` field when the message contains CV2 components, unlike the `Ephemeral` message flag that can be added when you defer an interaction response.
5
+
To use the display components, you need to pass the `IsComponentsV2` message flag (<DocsLinkpath="MessageFlags:Enum" />) when sending a message. You only need to use this flag when sending a message using the display components system, not when deffering interaction responses.
6
6
7
7
::: warning
8
-
Once a message is sent or edited with the `IsComponentsV2` message flag, the flag **cannot** be removed from that message.
8
+
Opting into using this system by passing the `IsComponentsV2` comes with a set of caveats:
9
+
- You **cannot** send `content`, `poll`, `embeds`, or `stickers`.
10
+
- You **cannot** opt out of using display components when editing a message
11
+
- You **can** opt into using display components when editing a message while explicitly setting `content`, `poll`, `embeds`, and `stickers` to null.
12
+
- Messages can have up to **40** total components (nested components count!)
13
+
- The amount of text across all text display components **cannot** exceed 4000 characters.
14
+
- All attached files have to explicitly be referenced in a component (refer to the [Thumbnail](/popular-topics/display-components#thumbnail), [Media Gallery](/popular-topics/display-components#media-gallery), and [file](/popular-topics/display-components#file) sections).
9
15
:::
10
16
11
-
All components have an `id` field (which should not be confused with the `custom_id` field for interactive components), which is an optional 32-bit integer identifier for a component presented in a message. It is used to identify non-interactive components in the response from an interaction. More information about these can be found [here](https://discord.com/developers/docs/components/reference#anatomy-of-a-component).
17
+
All components can be passed an optional, unique, `id` field holding a 32-bit integer identifier to later identify them in interaction responses. Do not confuse this with the `custom_id` field for interactive components! You can find more information about this [on the discord api documentation](https://discord.com/developers/docs/components/reference#anatomy-of-a-component). Discord will automatically populate the `id` of components that don't have the `id` specified in the payload sequentially starting from `1`. The `id` value `0` is treated as empty. The order components are automatically filled in is an implementation detail and not officially document. If you want to work with the `id` (for example to find and replace the content of a specific component lateron), you should explicitly specify it.
12
18
13
-
In the following section, we will explain all CV2 components in detail, how they work together with interactive components, and the limitations Discord has set when using CV2 components in your message.
19
+
In the following sections, we will explain all available display component types in detailand show you some examples on how you can use them.
14
20
15
21
## Text Display
16
22
17
-
A Text Display is a content component for adding markdown-formatted text to your message. This component is very similar to the `content` field of a message, but by using multiple Text Display components, you gain greater control over the layout of your message. You can use the <DocsLinkpath="TextDisplayBuilder:Class" /> class to easily create a Text Display component.
23
+
Text Display components let you add markdown-formatted text to your message and directly replace the `content` field when opting to use display components. You can use the <DocsLinkpath="TextDisplayBuilder:Class" /> class to easily create a Text Display component.
18
24
19
-
::: tip
20
-
In addition to the available markdown in Text Display components, you can also mention users and roles. In components, mentioned users and roles _will_ receive notifications, unlike when adding mentions to embeds. You can add the `allowedMentions`field to your message payload to control who will be notified.
25
+
::: danger
26
+
Sending user and role mentions in text display components**will notify users and roles**! You can and should control mentions with the `allowedMentions` message option.
21
27
:::
22
28
23
29
The example below shows how you can send a Text Display component in a channel.
@@ -38,9 +44,7 @@ await channel.send({
38
44
39
45
## Section
40
46
41
-
A Section is a layout component that places between one and three left-aligned Text Display components next to a right-aligned accessory (Thumbnail or Button component). At least one Text Display and the accessory are required. You can use the <DocsLinkpath="SectionBuilder:Class" /> class to easily create a Section component.
42
-
43
-
The example below shows how you can send a Section component in a channel containing three Text Display components with a Button component on the right, next to the text.
47
+
Sections represent text (one to three Text Display components) with an accessory. The accessory can either be an image (thumbnail) or button. If you do not want to send an accessory, use a [Text Display](/popular-topics/display-components.md#text-display) component instead. You can use the <DocsLinkpath="SectionBuilder:Class" /> class to easily create a Section component:
A Thumbnail is a content component that is visually similar to the `thumbnail` field inside an embed. Thumbnails are added an accessory inside a [Section](/popular-topics/components-v2.md#section) component, support alt text for accessibility, and can be marked as a spoiler. You can use the <DocsLinkpath="ThumbnailBuilder:Class" /> class to easily create a Thumbnail component.
75
-
76
-
The example below shows how you can send a Thumbnail component as a Section component accessory in a channel.
78
+
A Thumbnail is a display component that is visually similar to the `thumbnail` field inside an embed. Thumbnails are added as accessory inside a [Section](/popular-topics/display-components.md#section) component, support alt text for accessibility, and can be marked as a spoiler. You can use the <DocsLinkpath="ThumbnailBuilder:Class" /> class to easily create a Thumbnail component:
For more information how to set up custom attachments to use in your Thumbnail component URL, you can look at the guide for[attaching images in embeds](/popular-topics/embeds.md#attaching-images).
105
+
For more information about using attachments in components refer to the guide on[attaching images in embeds](/popular-topics/embeds.md#attaching-images).
104
106
105
107
## Media Gallery
106
108
107
-
A Media Gallery is a content component that can display up to 10 media attachments formatted in a structured gallery. Each attachment in the Media Gallery component can have an optional alt text (description) and can be marked as a spoiler. You can use the <DocsLinkpath="MediaGalleryBuilder:Class" /> and <DocsLinkpath="MediaGalleryItemBuilder:Class" /> classes to easily create a Media Gallery component and its items.
108
-
109
-
The example below shows how you can send a Media Gallery component in a channel.
109
+
A Media Gallery is a display component that can display a grid of up to 10 media attachments. Each media item can have an optional alt text (description) and can be marked as spoiler. You can use the <DocsLinkpath="MediaGalleryBuilder:Class" /> and <DocsLinkpath="MediaGalleryItemBuilder:Class" /> classes to easily create a Media Gallery component and its items:
A File is a content component that can display a single uploaded file attachment within the body of the message. By using multiple File components, you can upload and display multiple files in a single message. File components cannot have alt text (description), unlike a Thumbnail or Media Gallery component, but can be marked as a spoiler. You can use the <DocsLinkpath="FileBuilder:Class" /> class to easily create a File component.
139
-
140
-
The example below shows how you can send a File component in a channel.
138
+
A File is a display component that can display a single uploaded file within the body of the message. By using multiple File components, you can upload and display multiple files in a single message. File components cannot have alt texts (description), unlike a Thumbnail or Media Gallery component, but can be marked as a spoiler. You can use the <DocsLinkpath="FileBuilder:Class" /> class to easily create a File component:
A Container is a layout component which groups its child components inside a visually distinct rounded box with an optional accent color on the left, just like embeds. However, unlike embeds, not specifying a color will make the left side of the Container component match the background color. You can also mark the Container component as a spoiler, which blurs all content inside the container. You can use the <DocsLinkpath="ContainerBuilder:Class" /> class to easily create a Container component.
187
+
A Container is a layout component which groups its child components inside a visually distinct rounded box with an optional accent color on the left, similar to the message embed look. Unlike embeds, not specifying a color will make the left side of the Container component match the background color. You can mark Container components as spoiler, which blurs all content inside the container. You can use the <DocsLinkpath="ContainerBuilder:Class" /> class to easily create a Container component.
190
188
191
189
The example below shows how to send a Container component in a channel. It contains:
There are a few limits set by the Discord API to be aware of when using Components V2 in your messages. These limits are:
244
-
245
-
- To use any of the components listed under [New components](/popular-topics/components-v2.md#new-components) you must set the `IsComponentsV2` message flag in your message payload.
246
-
- Setting the `IsComponentsV2` message flag will disable the `content` and `embeds` fields. You can use [Text Display](/popular-topics/components-v2.md#text-display) and [Container](/popular-topics/components-v2.md#container) components as replacements.
247
-
- Setting the `IsComponentsV2` message flag will disable the `poll` and `stickers` fields, and there are no CV2 replacements for these fields you can use.
248
-
- When upgrading a message to a CV2 flagged message by editing the message with the `IsComponentsV2` flag, all mentioned fields in the message object (`content`, `embeds`, `poll` and `stickers`) need to be set to `null`.
249
-
- Attachments won't show by default, they must be set through the available media components ([Thumbnail](/popular-topics/components-v2.md#thumbnail), [Media Gallery](/popular-topics/components-v2.md#media-gallery) and [File](/popular-topics/components-v2.md#file)).
0 commit comments