Skip to content

Commit b7db108

Browse files
anthonydiscordanthonydiscord
authored
Modal Components (#7773)
* Modal components * Update images * Added modal string select image * Better wording * Removed unused image * Wording fixes * Fix wording and structure * Wording facepalm * Final updates
1 parent 92dccea commit b7db108

26 files changed

+1191
-818
lines changed

‎docs/change-log/2022-10-13-new-select-menu-components.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,6 @@ Four new select menu [component types](/docs/components/reference#component-obje
1010
* Mentionable (user *and* role) select (type `7`)
1111
* Channel select (type `8`)
1212

13-
The new select menu components are defined similarly to the existing string select menu—with the exception of not including the `options` field and, within channel select menus, having the option to include a `channel_types` field. The [select menu interaction](/docs/components/reference#string-select-string-select-interaction) apps receive also contain a [`resolved` field](/docs/components/reference#string-select-select-menu-resolved-object) for the new components.
13+
The new select menu components are defined similarly to the existing string select menu—with the exception of not including the `options` field and, within channel select menus, having the option to include a `channel_types` field. The [select menu interaction](/docs/components/reference#user-select-examples) apps receive also contain a [`resolved` field](/docs/components/reference#user-select-examples) for the new components.
1414

1515
More details can be found in the updated [select menu documentation](/docs/components/reference#component-object-component-types).

‎docs/change-log/2025-04-22-components-v2.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@ title: "Introducing New Components for Messages!"
33
date: "2025-04-22"
44
topics:
55
- "User Apps"
6-
- "HTTP API"
76
- "Interactions"
7+
- "Components"
88
---
99

1010
We're bringing new components to messages that you can use in your apps. They allow you to have full control over the layout of your messages.

‎docs/change-log/2025-04-29-component-limits.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@ title: "Raised Component Limits"
33
date: "2025-04-29"
44
topics:
55
- "User Apps"
6-
- "HTTP API"
76
- "Interactions"
7+
- "Components"
88
---
99

1010
We're removing the top level component limit and raising the limit on number of components in a message to 40 when using the [`IS_COMPONENTS_V2` message flag](/docs/resources/message#message-object-message-flags)! We're also removing the limit on the number of components in a [Container Component](/docs/components/reference#container). Legacy messages have not changed and continue to allow up to 5 action rows.

‎docs/components/reference.mdx

Lines changed: 1111 additions & 763 deletions
Large diffs are not rendered by default.

‎docs/components/using-modal-components.mdx

Lines changed: 53 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,6 @@ sidebar_label: Using Modal Components
88

99
Modal components are a great way to collect freeform information from your users.
1010

11-
:::info
12-
Currently, only [Text Input](/docs/components/reference#text-input) fields are supported in a modal, and each one must be placed in an [Action Row](/docs/components/reference#action-row).
13-
:::
14-
1511
### Prerequisites
1612

1713
- You must have a Discord account and be a member of the Discord Developer Portal.
@@ -21,50 +17,67 @@ Currently, only [Text Input](/docs/components/reference#text-input) fields are s
2117

2218
## Displaying a Modal
2319

24-
Displaying a modal can be done in response to a [slash command](/docs/tutorials/upgrading-to-application-commands#slash-commands) or when responding to an [interaction](/docs/interactions/receiving-and-responding). When displaying a modal you'll use an [interaction response](/docs/interactions/receiving-and-responding#interaction-response-object) with the [`MODAL`](/docs/interactions/receiving-and-responding#interaction-response-object-interaction-callback-type) interaction callback type and [modal fields](/docs/interactions/receiving-and-responding#interaction-response-object-modal).
20+
Displaying a modal can be done in response to an [interaction](/docs/interactions/receiving-and-responding). When displaying a modal you'll use an [interaction response](/docs/interactions/receiving-and-responding#interaction-response-object) with the [`MODAL`](/docs/interactions/receiving-and-responding#interaction-response-object-interaction-callback-type) interaction callback type and [modal fields](/docs/interactions/receiving-and-responding#interaction-response-object-modal).
2521

26-
An example of a modal with two Text Inputs:
22+
An example of a modal with a [String Select](/docs/components/reference#string-select) and [Text Input](/docs/components/reference#text-input) both wrapped in [Labels](/docs/components/reference#label):
2723

2824
```json
2925
{
30-
"type": 9,
31-
"data": {
32-
"custom_id": "feedback_modal",
33-
"title": "Submit Feedback",
34-
"components": [
26+
"type": 9,
27+
"data": {
28+
"custom_id": "bug_modal",
29+
"title": "Bug Report",
30+
"components": [
31+
{
32+
"type": 18,
33+
"label": "What's your favorite bug?",
34+
"component": {
35+
"type": 3,
36+
"custom_id": "bug_string_select",
37+
"placeholder": "Choose...",
38+
"options": [
39+
{
40+
"label": "Ant",
41+
"value": "ant",
42+
"description": "(best option)",
43+
"emoji": {
44+
"name": "🐜"
45+
}
46+
},
3547
{
36-
"type": 1,
37-
"components": [
38-
{
39-
"type": 4,
40-
"custom_id": "feedback_subject",
41-
"label": "Subject",
42-
"style": 1,
43-
"min_length": 1,
44-
"max_length": 100,
45-
"placeholder": "What is your feedback about?",
46-
"required": true
47-
}
48-
]
48+
"label": "Butterfly",
49+
"value": "butterfly",
50+
"emoji": {
51+
"name": "🦋"
52+
}
4953
},
5054
{
51-
"type": 1,
52-
"components": [
53-
{
54-
"type": 4,
55-
"custom_id": "feedback_details",
56-
"label": "Details",
57-
"style": 2,
58-
"min_length": 10,
59-
"max_length": 1000,
60-
"placeholder": "Please provide details...",
61-
"required": true
62-
}
63-
]
55+
"label": "Caterpillar",
56+
"value": "caterpillar",
57+
"emoji": {
58+
"name": "🐛"
59+
}
6460
}
65-
]
66-
}
61+
]
62+
}
63+
},
64+
{
65+
"type": 18,
66+
"label": "Why is it your favorite?",
67+
"description": "Please provide as much detail as possible!",
68+
"component": {
69+
"type": 4,
70+
"custom_id": "bug_explanation",
71+
"style": 2,
72+
"min_length": 1000,
73+
"max_length": 4000,
74+
"placeholder": "Write your explanation here...",
75+
"required": true
76+
}
77+
}
78+
]
79+
}
6780
}
6881
```
6982

70-
![Example of a modal with two text inputs one for subject and one for details](images/components/modal.webp)
83+
![Example of a modal with a String Select and a Text Input both wrapped in Labels](images/components/modal.webp)

‎docs/interactions/overview.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ A list of all message components and details on sending and receiving component
4949

5050
![Modals in the Discord client](images/overview-modals.webp)
5151

52-
The only interactive component that modals can contain are [text inputs](/docs/components/reference#text-input), which allow users to fill out single-or-multi line form inputs.
52+
The components that modals can contain are found in the [component reference](/docs/components/reference). The data received after a modal is submitted can be found in [each component's interaction response structure](/docs/interactions/receiving-and-responding#interaction-response-object-modal).
5353

5454
Details about creating and using modals is in the [Receiving and Responding](/docs/interactions/receiving-and-responding#interaction-response-object-modal) documentation.
5555

‎docs/interactions/receiving-and-responding.mdx

Lines changed: 22 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,15 @@ The values in `authorizing_integration_owners` depend on the key—
8787

8888
While the `data` field is guaranteed to be present for all [interaction types](/docs/interactions/receiving-and-responding#interaction-object-interaction-type) besides `PING`, its structure will vary. The following tables detail the inner `data` payload for each interaction type.
8989

90+
| Interaction Type | Interaction Data |
91+
|----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|
92+
| PING (`1`) | N / A |
93+
| APPLICATION_COMMAND (`2`) | [Application Command Data Structure](/docs/interactions/receiving-and-responding#interaction-object-application-command-data-structure) |
94+
| MESSAGE_COMPONENT (`3`) | [Message Component Data Structure](/docs/interactions/receiving-and-responding#interaction-object-message-component-data-structure) |
95+
| APPLICATION_COMMAND_AUTOCOMPLETE (`4`) | [Application Command Data Structure](/docs/interactions/receiving-and-responding#interaction-object-application-command-data-structure) |
96+
| MODAL_SUBMIT (`5`) | [Modal Submit Data Structure](/docs/interactions/receiving-and-responding#interaction-object-modal-submit-data-structure) |
97+
98+
9099
###### Application Command Data Structure
91100

92101
:::info
@@ -118,10 +127,17 @@ Sent in `APPLICATION_COMMAND` and `APPLICATION_COMMAND_AUTOCOMPLETE` interaction
118127

119128
###### Modal Submit Data Structure
120129

121-
| Field | Type | Description |
122-
|------------|----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
123-
| custom_id | string | [`custom_id`](/docs/components/reference#anatomy-of-a-component-custom-id) of the modal |
124-
| components | array of [message components](/docs/components/reference#component-object) | Values submitted by the user |
130+
| Field | Type | Description |
131+
|------------|-----------------------------------------------------------------------------------------------------------------------|--------------------------------------|
132+
| custom_id | string | The custom ID provided for the modal |
133+
| components | array of [modal submit component data](/docs/interactions/receiving-and-responding#interaction-response-object-modal) | Values submitted by the user |
134+
135+
###### Component Interaction Response Structures
136+
137+
| Component |
138+
|--------------------------------------------------------------------------------------------------------|
139+
| [String Select](/docs/components/reference#string-select-string-select-interaction-response-structure) |
140+
| [Text Input](/docs/components/reference#text-input-text-input-interaction-response-structure) |
125141

126142
###### Resolved Data Structure
127143

@@ -192,8 +208,8 @@ An [Interaction](/docs/interactions/receiving-and-responding#interaction-object)
192208
- [Slash Commands](/docs/interactions/application-commands#slash-commands-example-interaction)
193209
- [User Commands](/docs/interactions/application-commands#user-commands-example-interaction)
194210
- [Message Commands](/docs/interactions/application-commands#message-commands-example-interaction)
195-
- [Message Components](/docs/components/reference#button-button-interaction)
196-
- [Select Menu Message Components](/docs/components/reference#string-select-string-select-interaction)
211+
- [Message Components](/docs/components/using-message-components)
212+
- [Modal Components](/docs/components/using-modal-components)
197213

198214
An explanation of all the fields can be found in our [data models](/docs/interactions/receiving-and-responding#interaction-object).
199215

@@ -266,10 +282,6 @@ Not all message fields are currently supported.
266282

267283
###### Modal
268284

269-
:::warn
270-
Support for components in modals is currently limited to type 4 (Text Input).
271-
:::
272-
273285
| Field | Type | Description |
274286
|------------|--------------------------------------------------------------------|----------------------------------------------------------------|
275287
| custom_id | string | Developer-defined identifier for the modal, max 100 characters |

‎docs/resources/message.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ An app will receive empty values in the `content`, `embeds`, `attachments`, and
5353
| stickers? | array of [sticker](/docs/resources/sticker#sticker-object) objects | **Deprecated** the stickers sent with the message |
5454
| position? | integer | A generally increasing integer (there may be gaps or duplicates) that represents the approximate position of the message in a thread, it can be used to estimate the relative position of the message in a thread in company with `total_message_sent` on parent thread |
5555
| role_subscription_data? | [role subscription data](/docs/resources/message#role-subscription-data-object) object | data of the role subscription purchase or renewal that prompted this ROLE_SUBSCRIPTION_PURCHASE message |
56-
| resolved? | [resolved](/docs/interactions/receiving-and-responding#interaction-object-resolved-data-structure) data | data for users, members, channels, and roles in the message's [auto-populated select menus](/docs/components/reference#string-select-select-menu-resolved-object) |
56+
| resolved? | [resolved](/docs/interactions/receiving-and-responding#interaction-object-resolved-data-structure) data | data for users, members, channels, and roles in the message's [auto-populated select menus](/docs/interactions/receiving-and-responding#interaction-response-object-modal) |
5757
| poll? \[2\] | [poll](/docs/resources/poll#poll-object) object | A poll! |
5858
| call? | [message call](/docs/resources/message#message-call-object) object | the call associated with the message |
5959

‎static/images/components/action-row.webp

-192 Bytes
Binary file not shown.

‎static/images/components/channel-select.webp

-974 Bytes
Binary file not shown.

0 commit comments

Comments
 (0)