Skip to content

Commit 07ceead

Browse files
shaydewaelshaydewael
committed
start components v2 docs
1 parent 8c2479c commit 07ceead

File tree

4 files changed

+266
-77
lines changed

4 files changed

+266
-77
lines changed

‎docs/components/Overview.mdx

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Overview
2+
3+
TODO

‎docs/components/Types_of_Components.mdx

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
# Types of Components
2+
3+
TODO: Reference page
4+
5+
TODO: only 30 overall components in tree
6+
7+
## List of Components
8+
9+
The following is a complete table of available components. Details about each component are in the sections below.
10+
11+
TODO - ideally "category" labels are pills with icons
12+
13+
TODO - should "top-level" be included?
14+
15+
| Type | Name | Category | Description |
16+
| ---- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
17+
| 1 | [Action Row](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/action-row) | [Layout](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/layout-components) | Container to display a row of interactive components |
18+
| 9 | [Section](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/section) | [Layout](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/layout-components) | Container to display text alongside accessory content such as a thumbnail or button |
19+
| 12 | [Media Gallery](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/media-gallery) | [Layout](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/layout-components) | Container to display images and other media types |
20+
| 14 | [Separator](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/separator) | [Layout](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/layout-components) | Component to add vertical padding between top-level components |
21+
| 17 | [Container](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/embedded-container) | [Layout](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/layout-components) | Embedded container that visually groups a set of components |
22+
| 10 | [Text Display](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/text-display) | [Content](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/content-components) | Markdown text |
23+
| 11 | [Thumbnail](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/thumbnail) | [Content](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/content-components) | Small image that can be used as an accessory |
24+
| 13 | [File](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/file) | [Content](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/content-components) | Displays an attached file |
25+
| 2 | [Button](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/button) | [Interactive](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/interactive-components) | Button object |
26+
| 3 | [String Select](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/string-select) | [Interactive](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/interactive-components) | Select menu for picking from defined text options |
27+
| 4 | [Text Input](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/text-input) | [Interactive](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/interactive-components) | Text input object |
28+
| 5 | [User Select](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/user-select) | [Interactive](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/interactive-components) | Select menu for users |
29+
| 6 | [Role Select](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/role-select) | [Interactive](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/interactive-components) | Select menu for roles |
30+
| 7 | [Mentionable Select](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/mentionable-select) | [Interactive](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/interactive-components) | Select menu for mentionables (users *and* roles) |
31+
| 8 | [Channel Select](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/channel-select) | [Interactive](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/interactive-components) | Select menu for channels |
32+
33+
34+
## Layout Components
35+
36+
Layout components are used to order, group, and add spacing between [content](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS_CONTENT_COMPONENTS) and [interactive](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS_CONTENT_COMPONENTS) components.
37+
38+
### Action Row
39+
40+
Container that holds up to 5 [interactive components](#TODO) (excluding text input components, which can only be used in modals).
41+
42+
TODO: image of action row
43+
44+
By default, interactive components within an action row will be displayed inline, but may wrap to succeeding lines depending on the width of each component and the user's screen size.
45+
46+
###### Action Row Structure
47+
48+
| Field | Type | Description |
49+
| ---------- | ----------------------------------- | ----------------------------------------------------------------- |
50+
| type | integer | `1` for action row component |
51+
| components | array of [component objects](#TODO) | Up to 5 interactive [button](#TODO) or [select](#TODO) components |
52+
| id? | integer | Optional identifier for component |
53+
54+
###### Action Row Example
55+
56+
```json
57+
{
58+
"type": 1,
59+
"components": [
60+
{
61+
"id": 2,
62+
"type": 2,
63+
"label": "Click me!",
64+
"style": 1,
65+
"custom_id": "click_one"
66+
}
67+
]
68+
}
69+
```
70+
71+
### Section
72+
73+
TODO: up to 3 text components, only one accessory
74+
75+
TODO: image of section
76+
77+
### Embedded Container
78+
79+
Container that holds up to 10 components. Embedded containers are visually distinct from surrounding components, and have an optional color bar that you can customize to match your use case.
80+
81+
TODO: limits of what it can contain
82+
83+
TODO: image of embedded container
84+
85+
###### Embedded Container Structure
86+
87+
| Field | Type | Description |
88+
| ------------- | ----------------------------------- | -------------------------------------------------------------------------------- |
89+
| type | integer | `17` for container component |
90+
| components | array of [component objects](#TODO) | Up to 5 interactive [button](#TODO) or [select](#TODO) components |
91+
| accent_color? | ?integer | Color for the accent on the embedded container |
92+
| spoiler? | boolean | Whether the container should be a spoiler (or blurred out). Defaults to `false`. |
93+
| id? | integer | Optional identifier for component |
94+
95+
###### Embedded Container Example
96+
97+
```json
98+
{
99+
"type": 17,
100+
"components": [
101+
TODO
102+
]
103+
}
104+
```
105+
106+
### Separator
107+
108+
Component that adds vertical padding and visual division between other components.
109+
110+
TODO: image of separator ?
111+
112+
###### Separator Structure
113+
114+
| Field | Type | Description |
115+
| -------- | ------- | --------------------------------------------------------------------------------------- |
116+
| type | integer | `14` for separator component |
117+
| divider? | boolean | Whether a visual divider should be displayed in the component. Defaults to `true` |
118+
| spacing? | integer | Size of separator padding—`1` for small padding, `2` for large padding. Defaults to `1` |
119+
| id? | integer | Optional identifier for component |
120+
121+
###### Separator Example
122+
123+
```json
124+
{
125+
"type": 14,
126+
"divider": true,
127+
"spacing": 2
128+
}
129+
```
130+
131+
## Content Components
132+
133+
Content components allow you to display static text, images, and other media.
134+
135+
### Text Display
136+
137+
### Media
138+
139+
### File
140+
141+
TODO
142+
143+
#### Uploading a file
144+
145+
You can upload a file when sending a message and reference it within a file component using the `attachment://<filename>` syntax. Each file component can only display 1 attached file, but you can upload multiple files and add them to different file components within your payload.
146+
147+
> warn
148+
> Only `.jpg`, `.jpeg`, `.png`, `.webp`, and `.gif` file types are supported at this time.
149+
150+
To upload a file with your message, you'll need to send your payload as `multipart/form-data` (rather than `application/json`) and include your file with a valid filename in your payload. Details and examples for uploading files can be found in the [API Reference](#DOCS_REFERENCE/uploading-files).
151+
152+
### Thumbnail
153+
154+
## Interactive Components
155+
156+
Interactive components allow you to display actionable buttons, select menus, and inputs to users.
157+
158+
Interactive components must be contained in a parent component—all can be contained in an [action row](#TODO) component, and buttons can also be in a [section](#TODO) component's `accessory` field.
159+
160+
### Button
161+
162+
TODO: still porting
163+
164+
Buttons are clickable components that render in messages. They can be clicked by users, and send an [interaction](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object) to your app when clicked.
165+
166+
- Buttons must be sent inside an Action Row
167+
- An Action Row can contain up to 5 buttons
168+
- An Action Row containing buttons cannot also contain any select menu components
169+
170+
###### Button Structure
171+
172+
| Field | Type | Description |
173+
| ---------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
174+
| type | integer | `2` for a button |
175+
| style | integer | A [button style](#DOCS_INTERACTIONS_MESSAGE_COMPONENTS/button-object-button-styles) |
176+
| label? | string | Text that appears on the button; max 80 characters |
177+
| emoji? | partial [emoji](#DOCS_RESOURCES_EMOJI/emoji-object) | `name`, `id`, and `animated` |
178+
| custom_id? | string | Developer-defined identifier for the button; max 100 characters |
179+
| sku_id? | snowflake | Identifier for a purchasable [SKU](#DOCS_RESOURCES_SKU/sku-object), only available when using premium-style buttons |
180+
| url? | string | URL for link-style buttons |
181+
| disabled? | boolean | Whether the button is disabled (defaults to `false`) |
182+
| id? | integer | Optional identifier for component |
183+
184+
Buttons come in a variety of styles to convey different types of actions. These styles also define what fields are valid for a button.
185+
186+
- Non-link and Non-premium buttons **must** have a `custom_id`, and cannot have a `url` or a `sku_id`.
187+
- Link buttons **must** have a `url`, and cannot have a `custom_id`
188+
- Link buttons do not send an [interaction](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object) to your app when clicked
189+
- Premium buttons **must** contain a `sku_id`, and cannot have a `custom_id`, `label`, `url`, or `emoji`.
190+
- Premium buttons do not send an [interaction](#DOCS_INTERACTIONS_RECEIVING_AND_RESPONDING/interaction-object) to your app when clicked
191+
192+
###### Button Styles
193+
194+
Buttons can be in a variety of styles depending on your use case.
195+
196+
| Name | Value | Color | Required Field |
197+
| --------- | ----- | ------------------------ | -------------- |
198+
| Primary | 1 | blurple | `custom_id` |
199+
| Secondary | 2 | grey | `custom_id` |
200+
| Success | 3 | green | `custom_id` |
201+
| Danger | 4 | red | `custom_id` |
202+
| Link | 5 | grey, navigates to a URL | `url` |
203+
| Premium | 6 | blurple | `sku_id` |
204+
205+
TODO: has to be less intense way of displaying these
206+
207+
![An image showing the different button styles](button-styles.png)
208+
209+
### Select
210+
211+
TODO
212+
213+
#### String Select
214+
215+
#### User Select
216+
217+
#### Role Select
218+
219+
#### Mentionable Select
220+
221+
#### Channel Select
222+
223+
### Text Input

‎docs/components/Using_Components.mdx

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Using Components
2+
3+
## What is a Component
4+
5+
Components are a field on the [message object](#DOCS_RESOURCES_MESSAGE/message-object), so you can use them whether you're sending messages or responding to a [slash command](#DOCS_INTERACTIONS_APPLICATION_COMMANDS/) or other interaction.
6+
7+
### Component Object
8+
9+
TODO
10+
11+
12+
The structure of each component type is described in detail below.
13+
14+
###### Example Component
15+
16+
```json
17+
{
18+
"content": "This is a message with components",
19+
"components": [
20+
{
21+
"type": 1,
22+
"components": []
23+
}
24+
]
25+
}
26+
```
27+
28+
## Component Categories
29+
30+
TODO: maybe move
31+
32+
Components can have many different use cases—some are used to display simple texts, while others are used to contain and style other components. You can think of components as being a part of one of the following categories:
33+
- [**Layout components**](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/layout-components) can be used to order, group, and add visual styling in a message. The other categories of components typically must be added to one of the layout components.
34+
- [**Content components**](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/content-components) are used to display static text, images, and other media.
35+
- [**Interactive components**](#DOCS_COMPONENTS_TYPES_OF_COMPONENTS/interactive-components) are used to add interactive elements using elements like buttons and select menus.
36+
37+

0 commit comments

Comments
 (0)