Discord Components V2: Complete Guide
Components V2 turns a Discord message into a real layout tree: text, sections, thumbnails, media, separators, containers and interactive controls. This guide explains the model that Discord actually accepts and gives you an editable reference instead of a disconnected code fragment.
What changed in Components V2
Legacy webhook messages split presentation between top-level content and embeds. Components V2 moves the visible message into one components array and adds layout primitives such as Container and Section. Once the IS_COMPONENTS_V2 message flag is set, top-level content and embeds are disabled; text belongs in Text Display components instead.
The result is more composable than a legacy embed. A Container can hold formatted text, separators, media galleries, files and action rows behind one accent colour. A Section can place one to three text blocks beside a thumbnail or button accessory. You can mix several top-level blocks rather than forcing the whole design into one card.
The component types that matter
| Component | Use it for | Important rule |
|---|---|---|
| Text Display | Markdown text, headings, lists and mentions | Counts toward the message-wide character budget |
| Section | One to three text blocks beside a thumbnail or button | Its accessory is part of the Section |
| Thumbnail | Compact media beside Section text | Used as a Section accessory |
| Media Gallery | One or more large images or media items | Up to 10 items |
| Separator | A divider or deliberate vertical space | Can use small or large spacing |
| Container | An embed-like group with an optional accent colour | Containers cannot be nested |
| Action Row | Buttons or one select menu | Up to 5 buttons |
A minimal Components V2 webhook payload
This payload creates a coloured container with a heading, supporting text, a separator and a link button. The numeric flag is 32768, or 1 << 15. DWEEB adds the V2 flag when it serializes and sends a visual design.
{
"flags": 32768,
"components": [
{
"type": 17,
"accent_color": 5793266,
"components": [
{ "type": 10, "content": "# Server update\nEverything you need in one place." },
{ "type": 14, "divider": true, "spacing": 1 },
{
"type": 1,
"components": [
{ "type": 2, "style": 5, "label": "Read the guide", "url": "https://example.com/update" }
]
}
]
}
]
}Current message and nesting limits
DWEEB validates against the same limits before send, so the live issue list is also a practical limits calculator. Discord can change its API over time; the numbers below are generated from the constants used by the editor rather than copied into a second, drifting list.
- 40 components total, including nested components
- 10 top-level components
- 4,000 characters across text-bearing component fields
- 39 children in a Container when it is the only top-level component
- 1–3 Text Display children in a Section
- 10 Media Gallery items, 5 buttons per Action Row and 25 string-select options
Webhooks, buttons and app ownership
A person-created incoming webhook can post non-interactive Components V2 when the request opts into components. Link buttons are safe because Discord opens a URL and no application has to receive a click. Buttons with custom IDs and select menus are different: an application must own the webhook and acknowledge the interaction.
That distinction explains the setup badges in DWEEB. Static layouts work with any incoming webhook. DWEEB-hosted replies use a guided app-owned destination. Features that change roles, create channels or perform other privileged actions also require the relevant Discord app installation.
A reliable build workflow
The editable Components V2 showcase contains every major block and is a faster reference than assembling the numeric types by hand. Open it, select a component, and compare the visual tree with exported JSON.
- Start with information hierarchy: one purpose, one first action and only then decoration.
- Use Containers for visual grouping, not as a wrapper around every isolated line.
- Prefer a Section when a thumbnail or single button belongs directly to a short block of text.
- Validate character, nesting and interaction ownership before you copy or send JSON.
- Test the final post in a real channel; a preview cannot reproduce every client width or permission failure.
Put the guide into practice
Open the exact workflow in DWEEB. Nothing posts until you review and confirm it.
Open the editable Components V2 example →