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.
Sending the payload from a bot or your own code
The same components array works wherever the message is sent from, so a design checked visually does not have to be rebuilt in code. Only the transport and the flag handling differ.
- Export from the visual builder once the preview looks right, then paste the payload into your project
- Import a payload your code already sends to adjust it visually instead of editing braces
- Keep the numeric component types as the source of truth; builder classes in any library are wrappers over them
| Where you send it from | What to pass | What to watch |
|---|---|---|
| A webhook URL, directly over HTTPS | POST the JSON to the webhook URL with the components array and the V2 flag | Add ?with_components=true to the URL, or components are silently dropped |
| A bot library such as discord.js | Pass the same object through the library's message payload, or use its builder classes | Set the IS_COMPONENTS_V2 flag; content and embeds are rejected once it is set |
| A library without Components V2 helpers | Send the raw object — every library accepts a plain payload somewhere | Numeric type values are the contract; helper classes are convenience only |
| An AI client, through DWEEB's MCP connector | Ask for the message; the connector validates and previews before anything posts | It acts as your Discord account, so it reaches only what you can |
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 →