Component Reference

This document serves as a comprehensive reference for all available components. It covers three main categories:

Layout Components

For organizing and structuring content — Action Rows, Sections, Containers, Labels, and Separators.

Content Components

For displaying static text, images, and files — Text Display, Media Gallery, Thumbnails, and File.

Interactive Components

For user interactions — Buttons, Select Menus, Text Input, File Upload, Radio Group, and Checkboxes.

To use these components, you need to send the message flag 1 << 15 (IS_COMPONENTS_V2), which can be sent on a per-message basis. Once a message has been sent with this flag, it can’t be removed from that message. This enables the new components system with the following changes:

The content and embeds fields will no longer work — use Text Display and Container as replacements
Attachments won’t show by default — they must be exposed through components
The poll and stickers fields are disabled
Messages allow up to 40 total components

Legacy component behavior will continue to work but provides less flexibility and control over message layout.

For a practical guide on implementing these components, see Using Message Components and Using Modal Components.

What is a Component

Components allow you to style and structure your messages, modals, and interactions. They are interactive elements that can create rich user experiences in your Discord applications. Components are a field on the message object and modal. You can use them when creating messages or responding to an interaction, like an application command.

Component Types

The following is a complete table of available components.

Type	Name	Description	Style	Usage
1	Action Row	Container to display a row of interactive components	Layout	Message
2	Button	Button object	Interactive	Message
3	String Select	Select menu for picking from defined text options	Interactive	Message, Modal
4	Text Input	Text input object	Interactive	Modal
5	User Select	Select menu for users	Interactive	Message, Modal
6	Role Select	Select menu for roles	Interactive	Message, Modal
7	Mentionable Select	Select menu for mentionables (users and roles)	Interactive	Message, Modal
8	Channel Select	Select menu for channels	Interactive	Message, Modal
9	Section	Container to display text alongside an accessory component	Layout	Message
10	Text Display	Markdown text	Content	Message, Modal
11	Thumbnail	Small image that can be used as an accessory	Content	Message
12	Media Gallery	Display images and other media	Content	Message
13	File	Displays an attached file	Content	Message
14	Separator	Component to add vertical padding between other components	Layout	Message
17	Container	Container that visually groups a set of components	Layout	Message
18	Label	Container associating a label and description with a component	Layout	Modal
19	File Upload	Component for uploading files	Interactive	Modal
21	Radio Group	Single-choice set of options	Interactive	Modal
22	Checkbox Group	Multi-selectable group of checkboxes	Interactive	Modal
23	Checkbox	Single checkbox for yes/no choice	Interactive	Modal

Anatomy of a Component

All components have the following fields:

Field	Type	Description
type	integer	The type of the component
id?	integer	32-bit integer used as an optional identifier for the component

The id field is optional and is used to identify components in the response from an interaction. The id must be unique within the message and is generated sequentially if left empty. Generation of ids won’t use another id that exists in the message if you have one defined for another component. Sending components with an id of 0 is allowed but will be treated as empty and replaced by the API.

Custom ID

Additionally, interactive components like buttons and selects must have a custom_id field. The developer defines this field when sending the component payload, and it is returned in the interaction payload sent when a user interacts with the component. For example, if you set custom_id: click_me on a button, you’ll receive an interaction containing custom_id: click_me when a user clicks that button. custom_id is only available on interactive components and must be unique per component. Multiple components on the same message must not share the same custom_id. This field is a string of 1 to 100 characters and can be used flexibly to maintain state or pass through other important data.

Field	Type	Description
custom_id	string	Developer-defined identifier, 1–100 characters

Action Row

An Action Row is a top-level layout component. Action Rows can contain one of the following:

Up to 5 contextually grouped buttons
A single select component (String Select, User Select, Role Select, Mentionable Select, or Channel Select)

Label is recommended for use over an Action Row in modals. Action Row with Text Inputs in modals are now deprecated.

Action Row Structure

Field	Type	Description
type	integer	`1` for action row component
id?	integer	Optional identifier for component
components	array	Up to 5 Button components or a single select component

Child Components

Component	Description
Button	An Action Row can contain up to 5 Buttons
String Select	A single String Select
User Select	A single User Select
Role Select	A single Role Select
Mentionable Select	A single Mentionable Select
Channel Select	A single Channel Select

Message Example

Message create payload with an Action Row component

{
  "flags": 32768,
  "components": [
    {
      "type": 1,  // ComponentType.ACTION_ROW
      "components": [
        {
          "type": 2,  // ComponentType.BUTTON
          "custom_id": "click_yes",
          "label": "Accept",
          "style": 1
        },
        {
          "type": 2,  // ComponentType.BUTTON
          "label": "Learn More",
          "style": 5,
          "url": "http://watchanimeattheoffice.com/"
        },
        {
          "type": 2,  // ComponentType.BUTTON
          "custom_id": "click_no",
          "label": "Decline",
          "style": 4
        }
      ]
    }
  ]
}

Button

A Button is an interactive component that can only be used in messages. It creates clickable elements that users can interact with, sending an interaction to your app when clicked. Buttons must be placed inside an Action Row or a Section’s accessory field. Button Structure

Field	Type	Description
type	integer	`2` for a button
id?	integer	Optional identifier for component
style	integer	A button style
label?	string	Text that appears on the button; max 80 characters
emoji?	partial emoji	`name`, `id`, and `animated`
custom_id	string	Developer-defined identifier for the button; 1–100 characters
sku_id?	snowflake	Identifier for a purchasable SKU; only available for premium-style buttons
url?	string	URL for link-style buttons; max 512 characters
disabled?	boolean	Whether the button is disabled (defaults to `false`)

Non-link and non-premium buttons must have a custom_id, and cannot have a url or sku_id
Link buttons must have a url, and cannot have a custom_id — they do not send an interaction when clicked
Premium buttons must have a sku_id, and cannot have a custom_id, label, url, or emoji — they do not send an interaction when clicked

Button Styles

Name	Value	Action	Required Field
Primary	1	The most important or recommended action in a group	`custom_id`
Secondary	2	Alternative or supporting actions	`custom_id`
Success	3	Positive confirmation or completion actions	`custom_id`
Danger	4	An action with irreversible consequences	`custom_id`
Link	5	Navigates to a URL	`url`
Premium	6	Purchase	`sku_id`

Message Example

Message create payload with a Button component

{
  "flags": 32768,
  "components": [
    {
      "type": 1,  // ComponentType.ACTION_ROW
      "components": [
        {
          "type": 2,  // ComponentType.BUTTON
          "custom_id": "click_me",
          "label": "Click me!",
          "style": 1
        }
      ]
    }
  ]
}

Message Interaction Response Example

When a user interacts with a Button in a message

When a user interacts with a Button, this is the basic form of the interaction data payload you will receive.

{
  "type": 3,  // InteractionType.MESSAGE_COMPONENT
  // ...additionalInteractionFields

  "data": {
    "component_type": 2,  // ComponentType.BUTTON
    "id": 2,
    "custom_id": "click_me"
  }
}

Button Design Guidelines

Max 34 characters with icon or emoji; max 38 characters without
Keep text concise — use verbs that indicate the outcome of the action
Use clear, easily understandable language; avoid jargon
Maintain consistency in language and tone across buttons
Test button text for expansion or contraction in translated languages

Multiple Buttons: Use different button styles to create a hierarchy. Use only one Primary button per group. If multiple buttons are of equal significance, use Secondary for all. Premium Buttons automatically display the shop icon, SKU name, and SKU price — no additional configuration needed.

String Select

A String Select is an interactive component that allows users to select one or more provided options. It supports both single-select and multi-select behavior. When a user finishes making their choice(s), your app receives an interaction. String Selects are available in messages and modals. They must be placed inside an Action Row in messages and a Label in modals. String Select Structure

Field	Type	Description
type	integer	`3` for string select
id?	integer	Optional identifier for component
custom_id	string	ID for the select menu; 1–100 characters
options	array	Specified choices in a select menu; max 25
placeholder?	string	Placeholder text if nothing is selected; max 150 characters
min_values?*	integer	Minimum number of items that must be chosen (defaults to 1); min 0, max 25
max_values?	integer	Maximum number of items that can be chosen (defaults to 1); max 25
required?**	boolean	Whether the string select is required in a modal (defaults to `true`)
disabled?***	boolean	Whether select menu is disabled in a message (defaults to `false`)

* min_values must be omitted or at least 1 if required is omitted or true.
** The required field is only available for String Selects in modals; it is ignored in messages.
*** Using disabled in a modal will result in an error. Select Option Structure

Field	Type	Description
label	string	User-facing name of the option; max 100 characters
value	string	Dev-defined value of the option; max 100 characters
description?	string	Additional description of the option; max 100 characters
emoji?	partial emoji	`id`, `name`, and `animated`
default?	boolean	Will show this option as selected by default

Interaction Response Structure

Field	Type	Description
type*	integer	`3` for a String Select
component_type*	integer	`3` for a String Select
id	integer	Unique identifier for the component
custom_id	string	Developer-defined identifier; 1–100 characters
values	array of strings	The text of the selected options

* In message responses component_type is returned; in modal responses type is returned.

Message Example

Message create payload with a String Select component

{
  "flags": 32768,
  "components": [
    {
      "type": 1,  // ComponentType.ACTION_ROW
      "id": 1,
      "components": [
        {
          "type": 3,  // ComponentType.STRING_SELECT
          "id": 2,
          "custom_id": "favorite_bug",
          "placeholder": "Favorite bug?",
          "options": [
            { "label": "Ant", "value": "ant", "description": "(best option)", "emoji": {"name": "🐜"} },
            { "label": "Butterfly", "value": "butterfly", "emoji": {"name": "🦋"} },
            { "label": "Caterpillar", "value": "caterpillar", "emoji": {"name": "🐛"} }
          ]
        }
      ]
    }
  ]
}

Message Interaction Data Example

When a user interacts with a String Select in a message

{
  "type": 3,  // InteractionType.MESSAGE_COMPONENT
  // ...additionalInteractionFields

  "data": {
    "component_type": 3,  // ComponentType.STRING_SELECT
    "custom_id": "favorite_bug",
    "values": ["butterfly"]
  }
}

Modal Example

Modal create payload with a String Select component

{
  "type": 9,  // InteractionCallbackType.MODAL
  "data": {
    "custom_id": "bug_modal",
    "title": "Bug Survey",
    "components": [
      {
        "type": 18,  // ComponentType.LABEL
        "id": 1,
        "label": "Favorite bug?",
        "component": {
          "type": 3,  // ComponentType.STRING_SELECT
          "id": 2,
          "custom_id": "favorite_bug",
          "placeholder": "Ants are the best",
          "options": [
            { "label": "Ant", "value": "ant", "description": "(best option)", "emoji": {"name": "🐜"} },
            { "label": "Butterfly", "value": "butterfly", "emoji": {"name": "🦋"} },
            { "label": "Caterpillar", "value": "caterpillar", "emoji": {"name": "🐛"} }
          ]
        }
      }
    ]
  }
}

Modal Submit Interaction Data Example

When a user submits a modal containing a String Select

{
  "type": 5,  // InteractionType.MODAL_SUBMIT
  // ...additionalInteractionFields

  "data": {
    "custom_id": "bug_modal",
    "components": [
      {
        "type": 18,  // ComponentType.LABEL
        "id": 1,
        "component": {
          "type": 3,  // ComponentType.STRING_SELECT
          "id": 2,
          "custom_id": "favorite_bug",
          "values": ["butterfly"]
        }
      }
    ]
  }
}

Text Input

Text Input is an interactive component that allows users to enter free-form text responses in modals. It supports both short, single-line inputs and longer, multi-line paragraph inputs. Text Inputs can only be used within modals and must be placed inside a Label.

We no longer recommend using Text Input within an Action Row in modals. All Text Inputs should be placed inside a Label component going forward.

Text Input Structure

Field	Type	Description
type	integer	`4` for a text input
id?	integer	Optional identifier for component
custom_id	string	Developer-defined identifier for the input; 1–100 characters
style	integer	The Text Input Style
min_length?	integer	Minimum input length; min 0, max 4000
max_length?	integer	Maximum input length; min 1, max 4000
required?	boolean	Whether this component is required to be filled (defaults to `true`)
value?	string	Pre-filled value for this component; max 4000 characters
placeholder?	string	Custom placeholder text if the input is empty; max 100 characters

The label field on a Text Input is deprecated in favor of label and description on the Label component.

Text Input Styles

Name	Value	Description
Short	1	Single-line input
Paragraph	2	Multi-line input

Interaction Response Structure

Field	Type	Description
type	integer	`4` for a Text Input
id	integer	Unique identifier for the component
custom_id	string	Developer-defined identifier; 1–100 characters
value	string	The user’s input text

Modal Example

Modal create payload with a Text Input component

{
  "type": 9,  // InteractionCallbackType.MODAL
  "data": {
    "custom_id": "game_feedback_modal",
    "title": "Game Feedback",
    "components": [
      {
        "type": 18,  // ComponentType.LABEL
        "label": "What did you find interesting about the game?",
        "description": "Please give us as much detail as possible so we can improve the game!",
        "component": {
          "type": 4,  // ComponentType.TEXT_INPUT
          "custom_id": "game_feedback",
          "style": 2,
          "min_length": 100,
          "max_length": 4000,
          "placeholder": "Write your feedback here...",
          "required": true
        }
      }
    ]
  }
}

Modal Submit Interaction Data Example

When a user submits a modal containing a Text Input

{
  "type": 5,  // InteractionType.MODAL_SUBMIT
  // ...additionalInteractionFields

  "data": {
    "custom_id": "game_feedback_modal",
    "components": [
      {
        "type": 18,  // ComponentType.LABEL
        "id": 1,
        "component": {
          "type": 4,  // ComponentType.TEXT_INPUT
          "id": 2,
          "custom_id": "game_feedback",
          "value": "The recent changes to acceleration feel much better, but shadows still need help"
        }
      }
    ]
  }
}

User Select

A User Select is an interactive component that allows users to select one or more users in a message or modal. Options are automatically populated based on the server’s available users. User Selects must be placed inside an Action Row in messages and a Label in modals. User Select Structure

Field	Type	Description
type	integer	`5` for user select
id?	integer	Optional identifier for component
custom_id	string	ID for the select menu; 1–100 characters
placeholder?	string	Placeholder text if nothing is selected; max 150 characters
default_values?	array	List of default values; count must be within `min_values`/`max_values` range
min_values?*	integer	Minimum number of items that must be chosen (defaults to 1); min 0, max 25
max_values?	integer	Maximum number of items that can be chosen (defaults to 1); max 25
required?**	boolean	Whether the user select is required in a modal (defaults to `true`)
disabled?***	boolean	Whether select menu is disabled in a message (defaults to `false`)

Select Default Value Structure

Field	Type	Description
id	snowflake	ID of a user, role, or channel
type	string	Type of value — `"user"`, `"role"`, or `"channel"`

Message Example

Message create payload with a User Select component

{
  "flags": 32768,
  "components": [
    {
      "type": 1,  // ComponentType.ACTION_ROW
      "components": [
        {
          "type": 5,  // ComponentType.USER_SELECT
          "custom_id": "user_select",
          "placeholder": "Select a user"
        }
      ]
    }
  ]
}

Modal Example

Modal create payload with a User Select component

{
  "type": 9,
  "data": {
    "custom_id": "user_modal",
    "title": "User Chooser",
    "components": [
      {
        "type": 18,  // ComponentType.LABEL
        "label": "Choose your users",
        "component": {
          "type": 5,  // ComponentType.USER_SELECT
          "custom_id": "user_selected",
          "max_values": 5,
          "required": true
        }
      }
    ]
  }
}

Role Select

A Role Select is an interactive component that allows users to select one or more roles. Options are automatically populated based on the server’s available roles. Role Selects must be placed inside an Action Row in messages and a Label in modals. Role Select Structure

Field	Type	Description
type	integer	`6` for role select
id?	integer	Optional identifier for component
custom_id	string	ID for the select menu; 1–100 characters
placeholder?	string	Placeholder text if nothing is selected; max 150 characters
default_values?	array	List of default values
min_values?*	integer	Minimum number of items that must be chosen (defaults to 1); min 0, max 25
max_values?	integer	Maximum number of items that can be chosen (defaults to 1); max 25
required?**	boolean	Whether the role select is required in a modal (defaults to `true`)
disabled?***	boolean	Whether select menu is disabled in a message (defaults to `false`)

Message Example

Message create payload with a Role Select component

{
  "flags": 32768,
  "components": [
    {
      "type": 1,  // ComponentType.ACTION_ROW
      "components": [
        {
          "type": 6,  // ComponentType.ROLE_SELECT
          "custom_id": "role_ids",
          "placeholder": "Which roles?",
          "min_values": 1,
          "max_values": 3
        }
      ]
    }
  ]
}

Modal Example

Modal create payload with a Role Select component

{
  "type": 9,
  "data": {
    "custom_id": "role_modal",
    "title": "Role Select",
    "components": [
      {
        "type": 18,
        "label": "Select which roles to assign",
        "component": {
          "type": 6,
          "custom_id": "roles_selected",
          "max_values": 10,
          "required": true
        }
      }
    ]
  }
}

Mentionable Select

A Mentionable Select is an interactive component that allows users to select one or more mentionables (users and roles) in a message or modal. Options are automatically populated based on available mentionables in the server. Mentionable Selects must be placed inside an Action Row in messages and a Label in modals. Mentionable Select Structure

Field	Type	Description
type	integer	`7` for mentionable select
id?	integer	Optional identifier for component
custom_id	string	ID for the select menu; 1–100 characters
placeholder?	string	Placeholder text if nothing is selected; max 150 characters
default_values?	array	List of default values
min_values?*	integer	Minimum number of items that must be chosen (defaults to 1); min 0, max 25
max_values?	integer	Maximum number of items that can be chosen (defaults to 1); max 25
required?**	boolean	Whether the mentionable select is required in a modal (defaults to `true`)
disabled?***	boolean	Whether select menu is disabled in a message (defaults to `false`)

Message Example

Message create payload with a Mentionable Select component

{
  "flags": 32768,
  "components": [
    {
      "type": 1,  // ComponentType.ACTION_ROW
      "components": [
        {
          "type": 7,  // ComponentType.MENTIONABLE_SELECT
          "custom_id": "who_to_ping",
          "placeholder": "Who?"
        }
      ]
    }
  ]
}

Modal Example

Modal create payload with a Mentionable Select component

{
  "type": 9,
  "data": {
    "custom_id": "mentionable_modal",
    "title": "Unmentionables",
    "components": [
      {
        "type": 18,
        "label": "Who gets mentioned?",
        "component": {
          "type": 7,
          "custom_id": "mentionables_selected",
          "required": true
        }
      }
    ]
  }
}

Channel Select

A Channel Select is an interactive component that allows users to select one or more channels. Options are automatically populated based on available channels in the server and can be filtered by channel type. Channel Selects must be placed inside an Action Row in messages and a Label in modals. Channel Select Structure

Field	Type	Description
type	integer	`8` for channel select
id?	integer	Optional identifier for component
custom_id	string	ID for the select menu; 1–100 characters
channel_types?	array	List of channel types to include in the select
placeholder?	string	Placeholder text if nothing is selected; max 150 characters
default_values?	array	List of default values
min_values?*	integer	Minimum number of items that must be chosen (defaults to 1); min 0, max 25
max_values?	integer	Maximum number of items that can be chosen (defaults to 1); max 25
required?**	boolean	Whether the channel select is required in a modal (defaults to `true`)
disabled?***	boolean	Whether select menu is disabled in a message (defaults to `false`)

Message Example

Message create payload with a Channel Select component

{
  "flags": 32768,
  "components": [
    {
      "type": 1,  // ComponentType.ACTION_ROW
      "components": [
        {
          "type": 8,  // ComponentType.CHANNEL_SELECT
          "custom_id": "notification_channel",
          "channel_types": [0],  // ChannelType.TEXT
          "placeholder": "Which text channel?"
        }
      ]
    }
  ]
}

Modal Example

Modal create payload with a Channel Select component

{
  "type": 9,
  "data": {
    "custom_id": "channel_modal",
    "title": "Lockdown",
    "components": [
      {
        "type": 18,
        "label": "Which channel should be locked?",
        "component": {
          "type": 8,
          "custom_id": "channel_selected",
          "required": true
        }
      }
    ]
  }
}

Section

A Section is a top-level layout component that allows you to contextually associate content with an accessory component. The typical use-case is to associate Text Display content with an accessory. Sections are currently only available in messages.

To use this component, you must send the message flag 1 << 15 (IS_COMPONENTS_V2).

Section Structure

Field	Type	Description
type	integer	`9` for section component
id?	integer	Optional identifier for component
components	array	1–3 child components representing the content of the section
accessory	component	A component contextually associated to the section content

Child Components: Text Display Accessory Components: Button, Thumbnail

Message Example

Message create payload with a Section and Thumbnail component

{
  "flags": 32768,
  "components": [
    {
      "type": 9,  // ComponentType.SECTION
      "components": [
        {
          "type": 10,  // ComponentType.TEXT_DISPLAY
          "content": "# Real Game v7.3"
        },
        {
          "type": 10,  // ComponentType.TEXT_DISPLAY
          "content": "Hope you're excited, the update is finally here! Here are some of the changes:\n- Fixed a bug where certain treasure chests wouldn't open properly\n- Improved server stability during peak hours\n- Added a new type of gravity that will randomly apply when the moon is visible in-game"
        }
      ],
      "accessory": {
        "type": 11,  // ComponentType.THUMBNAIL
        "media": {
          "url": "https://websitewithopensourceimages/gamepreview.webp"
        }
      }
    }
  ]
}

Text Display

A Text Display is a content component that allows you to add markdown-formatted text, including mentions (users, roles, etc.) and emojis. Its behavior is similar to the content field of a message, but you can add multiple Text Display components to control the layout of your message. Pingable mentions in a Text Display will ping and send notifications based on the allowed mentions object in message.allowed_mentions.

To use this component in messages, you must send the message flag 1 << 15 (IS_COMPONENTS_V2).

Text Display Structure

Field	Type	Description
type	integer	`10` for text display
id?	integer	Optional identifier for component
content	string	Text that will be displayed similar to a message

Message Example

Message create payload with a Text Display component

{
  "flags": 32768,
  "components": [
    {
      "type": 10,  // ComponentType.TEXT_DISPLAY
      "content": "# This is a Text Display\nAll the regular markdown rules apply\n- You can make lists\n- You can use `code blocks`\n- You can use [links](http://watchanimeattheoffice.com/)\n- Even :blush: :star_struck: :exploding_head:\n- Spoiler alert: ||these too!||"
    }
  ]
}

Modal Example

Modal create payload with a Text Display component

{
  "type": 9,
  "data": {
    "custom_id": "jail_modal",
    "title": "Jail",
    "components": [
      {
        "type": 10,
        "content": "This action will move the selected user to the selected voice channel and take away all their permissions **for 1 hour**."
      },
      {
        "type": 18,
        "label": "Choose a user",
        "component": { "type": 5, "custom_id": "user_selected", "required": true }
      },
      {
        "type": 18,
        "label": "Where should they be sent?",
        "component": { "type": 8, "custom_id": "channel_selected", "channel_types": [2], "required": true }
      }
    ]
  }
}

Thumbnail

A Thumbnail is a content component that displays visual media in a small form-factor, intended as an accessory to other content. It is primarily usable with Sections. Media is defined by the Unfurled Media Item structure, which supports both uploaded and external media. Thumbnails are only available in messages as an accessory within a Section. They support images including animated formats like GIF and WebP. Videos are not currently supported.

To use this component, you must send the message flag 1 << 15 (IS_COMPONENTS_V2).

Thumbnail Structure

Field	Type	Description
type	integer	`11` for thumbnail component
id?	integer	Optional identifier for component
media	unfurled media item	A URL or attachment provided as an Unfurled Media Item
description?	string	Alt text for the media; max 1024 characters
spoiler?	boolean	Whether the thumbnail should be blurred out (defaults to `false`)

Media Gallery

A Media Gallery is a top-level content component that allows you to display 1–10 media attachments in an organized gallery format. Each item can have optional descriptions and can be marked as spoilers. Media Galleries are only available in messages.

To use this component, you must send the message flag 1 << 15 (IS_COMPONENTS_V2).

Media Gallery Structure

Field	Type	Description
type	integer	`12` for media gallery component
id?	integer	Optional identifier for component
items	array	1–10 media gallery items

Media Gallery Item Structure

Field	Type	Description
media	unfurled media item	A URL or attachment provided as an Unfurled Media Item
description?	string	Alt text for the media; max 1024 characters
spoiler?	boolean	Whether the media should be blurred out (defaults to `false`)

Message Example

Message create payload with a Media Gallery component

{
  "flags": 32768,
  "components": [
    {
      "type": 10,  // ComponentType.TEXT_DISPLAY
      "content": "Live webcam shots as of 18-04-2025 at 12:00 UTC"
    },
    {
      "type": 12,  // ComponentType.MEDIA_GALLERY
      "items": [
        {
          "media": {"url": "https://livevideofeedconvertedtoimage/webcam1.webp"},
          "description": "An aerial view looking down on older industrial complex buildings."
        },
        {
          "media": {"url": "https://livevideofeedconvertedtoimage/webcam2.webp"},
          "description": "An aerial view of old broken buildings with nature taking root on the rooftops."
        },
        {
          "media": {"url": "https://livevideofeedconvertedtoimage/webcam3.webp"},
          "description": "A street view of a downtown city with skyscrapers and a domed building."
        }
      ]
    }
  ]
}

File

A File is a top-level content component that allows you to display an uploaded file as an attachment to a message. Each File component can only display 1 attached file, but you can upload multiple files and reference them from different File components within your payload. Files are only available in messages.

The File component only supports using the attachment:// protocol in Unfurled Media Item.

To use this component, you must send the message flag 1 << 15 (IS_COMPONENTS_V2).

File Structure

Field	Type	Description
type	integer	`13` for a file component
id?	integer	Optional identifier for component
file	unfurled media item	Supports only `attachment://<filename>` syntax
spoiler?	boolean	Whether the media should be blurred out (defaults to `false`)
name?	string	Name of the file — ignored in requests, provided by API in responses
size?	integer	Size of the file in bytes — ignored in requests, provided by API in responses

Message Example

Message create payload with a File component

{
  "flags": 32768,
  "components": [
    {
      "type": 10,  // ComponentType.TEXT_DISPLAY
      "content": "# New game version released for testing!\nGrab the game here:"
    },
    {
      "type": 13,  // ComponentType.FILE
      "file": { "url": "attachment://game.zip" }
    },
    {
      "type": 10,  // ComponentType.TEXT_DISPLAY
      "content": "Latest manual artwork here:"
    },
    {
      "type": 13,  // ComponentType.FILE
      "file": { "url": "attachment://manual.pdf" }
    }
  ]
}

Separator

A Separator is a top-level layout component that adds vertical padding and visual division between other components. Separators are only available in messages.

To use this component, you must send the message flag 1 << 15 (IS_COMPONENTS_V2).

Separator Structure

Field	Type	Description
type	integer	`14` for separator component
id?	integer	Optional identifier for component
divider?	boolean	Whether a visual divider line should be displayed (defaults to `true`)
spacing?	integer	Size of separator padding — `1` for small, `2` for large (defaults to `1`)

Message Example

Message create payload with a Separator component

{
  "flags": 32768,
  "components": [
    {
      "type": 10,  // ComponentType.TEXT_DISPLAY
      "content": "It's dangerous to go alone!"
    },
    {
      "type": 14,  // ComponentType.SEPARATOR
      "divider": true,
      "spacing": 1
    },
    {
      "type": 10,  // ComponentType.TEXT_DISPLAY
      "content": "Take this."
    }
  ]
}

Container

A Container is a top-level layout component that visually encapsulates a collection of components with an optional customizable accent color bar. Containers are only available in messages.

To use this component, you must send the message flag 1 << 15 (IS_COMPONENTS_V2).

Container Structure

Field	Type	Description
type	integer	`17` for container component
id?	integer	Optional identifier for component
components	array	Child components encapsulated within the Container
accent_color?	integer	Color for the accent bar as RGB from `0x000000` to `0xFFFFFF`
spoiler?	boolean	Whether the container should be blurred out (defaults to `false`)

Container Child Components: Action Row, Text Display, Section, Media Gallery, Separator, File

Message Example

Message create payload with a Container component

{
  "flags": 32768,
  "components": [
    {
      "type": 17,  // ComponentType.CONTAINER
      "accent_color": 703487,
      "components": [
        {
          "type": 10,  // ComponentType.TEXT_DISPLAY
          "content": "# You have encountered a wild coyote!"
        },
        {
          "type": 12,  // ComponentType.MEDIA_GALLERY
          "items": [
            { "media": {"url": "https://websitewithopensourceimages/coyote.webp"} }
          ]
        },
        {
          "type": 10,  // ComponentType.TEXT_DISPLAY
          "content": "What would you like to do?"
        },
        {
          "type": 1,  // ComponentType.ACTION_ROW
          "components": [
            { "type": 2, "custom_id": "pet_coyote", "label": "Pet it!", "style": 1 },
            { "type": 2, "custom_id": "feed_coyote", "label": "Attempt to feed it", "style": 2 },
            { "type": 2, "custom_id": "run_away", "label": "Run away!", "style": 4 }
          ]
        }
      ]
    }
  ]
}

Label

A Label is a top-level layout component for modals. It wraps interactive modal components with a text label and an optional description.

The description may display above or below the component depending on the platform.

Label Structure

Field	Type	Description
type	integer	`18` for a label
id?	integer	Optional identifier for component
label	string	The label text; max 45 characters
description?	string	An optional description text; max 100 characters
component	component	The component within the label

Label Child Components: Text Input, String Select, User Select, Role Select, Mentionable Select, Channel Select, File Upload, Radio Group, Checkbox Group, Checkbox

Modal Example

Modal create payload with a Label component wrapping a Text Input

{
  "type": 9,  // InteractionCallbackType.MODAL
  "data": {
    "custom_id": "game_feedback_modal",
    "title": "Game Feedback",
    "components": [
      {
        "type": 18,  // ComponentType.LABEL
        "label": "What did you find interesting about the game?",
        "description": "Please give us as much detail as possible so we can improve the game!",
        "component": {
          "type": 4,  // ComponentType.TEXT_INPUT
          "custom_id": "game_feedback",
          "style": 2,
          "min_length": 100,
          "max_length": 4000,
          "placeholder": "Write your feedback here...",
          "required": true
        }
      }
    ]
  }
}

File Upload

File Upload is an interactive component that allows users to upload files in modals. It supports configuring minimum and maximum file counts (0–10) and a required flag for submission. The maximum file size a user can upload is based on their upload limit in that channel. File Uploads are only available in modals and must be placed inside a Label. File Upload Structure

Field	Type	Description
type	integer	`19` for file upload
id?	integer	Optional identifier for component
custom_id	string	ID for the file upload; 1–100 characters
min_values?*	integer	Minimum number of files that must be uploaded (defaults to 1); min 0, max 10
max_values?	integer	Maximum number of files that can be uploaded (defaults to 1); max 10
required?	boolean	Whether files are required before submitting the modal (defaults to `true`)

Interaction Response Structure

Field	Type	Description
type	integer	`19` for a File Upload
id	integer	Unique identifier for the component
custom_id	string	Developer-defined identifier; 1–100 characters
values	array of snowflakes	IDs of the uploaded files in the resolved data

Modal Example

Modal create payload with a File Upload component

{
  "type": 9,
  "data": {
    "custom_id": "bug_submit_modal",
    "title": "Bug Submission",
    "components": [
      {
        "type": 18,  // ComponentType.LABEL
        "label": "File Upload",
        "description": "Please upload a screenshot or other image that shows the bug you encountered.",
        "component": {
          "type": 19,  // ComponentType.FILE_UPLOAD
          "custom_id": "file_upload",
          "min_values": 1,
          "max_values": 10,
          "required": true
        }
      }
    ]
  }
}

Modal Submit Interaction Data Example

When a user submits a modal containing a File Upload

{
  "type": 5,  // InteractionType.MODAL_SUBMIT
  // ...additionalInteractionFields

  "data": {
    "custom_id": "bug_submit_modal",
    "components": [
      {
        "id": 1,
        "type": 18,  // ComponentType.LABEL
        "component": {
          "custom_id": "file_upload",
          "id": 2,
          "type": 19,  // ComponentType.FILE_UPLOAD
          "values": ["111111111111111111111"]
        }
      }
    ],
    "resolved": {
      "attachments": {
        "111111111111111111111": {
          "content_type": "image/png",
          "ephemeral": true,
          "filename": "bug.png",
          "height": 604,
          "id": "111111111111111111111",
          "size": 241394,
          "width": 2482
        }
      }
    }
  }
}

Radio Group

A Radio Group is an interactive component for selecting exactly one option from a defined list. Radio Groups are available in modals and must be placed inside a Label. Radio Group Structure

Field	Type	Description
type	integer	`21` for radio group
id?	integer	Optional identifier for component
custom_id	string	Developer-defined identifier; 1–100 characters
options	array	List of options to show; min 2, max 10
required?	boolean	Whether a selection is required to submit the modal (defaults to `true`)

Radio Group Option Structure

Field	Type	Description
value	string	Dev-defined value of the option; max 100 characters
label	string	User-facing label of the option; max 100 characters
description?	string	Optional description for the option; max 100 characters
default?	boolean	Shows the option as selected by default

Interaction Response Structure

Field	Type	Description
type	integer	`21` for a Radio Group
id	integer	Unique identifier for the component
custom_id	string	Developer-defined identifier; 1–100 characters
value	?string	The value of the selected option, or `null` if none selected

Modal Example

Modal create payload with a Radio Group component

{
  "type": 9,
  "data": {
    "custom_id": "class_selection_modal",
    "title": "Class Selection",
    "components": [
      {
        "type": 18,  // ComponentType.LABEL
        "label": "Choose your class",
        "description": "Your class determines the style of play for your character.",
        "component": {
          "type": 21,  // ComponentType.RADIO_GROUP
          "custom_id": "class_radio",
          "options": [
            {"value": "warrior", "label": "Warrior", "description": "Strong and brave"},
            {"value": "rogue", "label": "Rogue", "description": "Weak and squishy"},
            {"value": "wizard", "label": "Wizard", "description": "Nerd"},
            {"value": "bard", "label": "Bard", "description": "Annoys everyone"},
            {"value": "witch_doctor", "label": "Witch Doctor", "description": "Actually a pretty cool option"}
          ]
        }
      }
    ]
  }
}

Modal Submit Interaction Data Example

When a user submits a modal containing a Radio Group

{
  "type": 5,  // InteractionType.MODAL_SUBMIT
  // ...additionalInteractionFields

  "data": {
    "custom_id": "class_selection_modal",
    "components": [
      {
        "id": 1,
        "type": 18,  // ComponentType.LABEL
        "component": {
          "custom_id": "class_radio",
          "id": 2,
          "type": 21,  // ComponentType.RADIO_GROUP
          "value": "warrior"
        }
      }
    ]
  }
}

Checkbox Group

A Checkbox Group is an interactive component for selecting one or many options via checkboxes. Checkbox Groups are available in modals and must be placed inside a Label. Checkbox Group Structure

Field	Type	Description
type	integer	`22` for checkbox group
id?	integer	Optional identifier for component
custom_id	string	Developer-defined identifier; 1–100 characters
options	array	List of options to show; min 1, max 10
min_values?*	integer	Minimum number of items that must be chosen; min 0, max 10 (defaults to 1)
max_values?	integer	Maximum number of items that can be chosen; min 1, max 10 (defaults to number of options)
required?	boolean	Whether selecting within the group is required (defaults to `true`)

Checkbox Group Option Structure

Field	Type	Description
value	string	Dev-defined value of the option; max 100 characters
label	string	User-facing label of the option; max 100 characters
description?	string	Optional description for the option; max 100 characters
default?	boolean	Shows the option as selected by default

Interaction Response Structure

Field	Type	Description
type	integer	`22` for a Checkbox Group
id	integer	Unique identifier for the component
custom_id	string	Developer-defined identifier; 1–100 characters
values	array of strings	The values of the selected options, or `[]` if none selected

Modal Example

Modal create payload with a Checkbox Group component

{
  "type": 9,
  "data": {
    "custom_id": "day_selection_modal",
    "title": "Study Days",
    "components": [
      {
        "type": 18,  // ComponentType.LABEL
        "label": "Which days are you free?",
        "description": "Choose all of the days you're able to meet up.",
        "component": {
          "type": 22,  // ComponentType.CHECKBOX_GROUP
          "custom_id": "event_checkbox",
          "options": [
            {"value": "march-4", "label": "March 4th"},
            {"value": "march-5", "label": "March 5th"},
            {"value": "march-7", "label": "March 7th", "description": "I know this is a Saturday and is tough"},
            {"value": "march-9", "label": "March 9th"},
            {"value": "march-10", "label": "March 10th"}
          ]
        }
      }
    ]
  }
}

Modal Submit Interaction Data Example

When a user submits a modal containing a Checkbox Group

{
  "type": 5,  // InteractionType.MODAL_SUBMIT
  // ...additionalInteractionFields

  "data": {
    "custom_id": "day_selection_modal",
    "components": [
      {
        "id": 1,
        "type": 18,  // ComponentType.LABEL
        "component": {
          "custom_id": "event_checkbox",
          "id": 2,
          "type": 22,  // ComponentType.CHECKBOX_GROUP
          "values": ["march-5", "march-10", "march-4"]
        }
      }
    ]
  }
}

Checkbox

A Checkbox is a single interactive component for simple yes/no style questions. Checkboxes are available in modals and must be placed inside a Label. Checkbox Structure

Field	Type	Description
type	integer	`23` for checkbox
id?	integer	Optional identifier for component
custom_id	string	Developer-defined identifier; 1–100 characters
default?	boolean	Whether the checkbox is selected by default

While you can’t set a Checkbox as required, you can use a Checkbox Group with a single option and required: true to achieve similar functionality.

Interaction Response Structure

Field	Type	Description
type	integer	`23` for a Checkbox
id	integer	Unique identifier for the component
custom_id	string	Developer-defined identifier; 1–100 characters
value	boolean	The state of the checkbox (`true` if checked, `false` if unchecked)

Modal Example

Modal create payload with a Checkbox component

{
  "type": 9,
  "data": {
    "custom_id": "secret_note_modal",
    "title": "Secret Note",
    "components": [
      {
        "type": 18,  // ComponentType.LABEL
        "label": "Do you like me?",
        "component": {
          "type": 23,  // ComponentType.CHECKBOX
          "custom_id": "like_checkbox"
        }
      }
    ]
  }
}

Modal Submit Interaction Data Example

When a user submits a modal containing a Checkbox

{
  "type": 5,  // InteractionType.MODAL_SUBMIT
  // ...additionalInteractionFields

  "data": {
    "custom_id": "secret_note_modal",
    "components": [
      {
        "id": 1,
        "type": 18,  // ComponentType.LABEL
        "component": {
          "custom_id": "like_checkbox",
          "id": 2,
          "type": 23,  // ComponentType.CHECKBOX
          "value": true
        }
      }
    ]
  }
}

Unfurled Media Item

An Unfurled Media Item is a piece of media, represented by a URL, used within a component. It can be constructed via uploading media to Discord or by referencing external media via a direct link to the asset.

Only the url field is settable by developers when making requests. All other fields are automatically populated by Discord.

Unfurled Media Item Structure

Field	Type	Description
url	string	Supports arbitrary URLs and `attachment://<filename>` references
proxy_url?	string	The proxied URL — provided by the API in responses
height?	integer	The height of the media item — provided by the API in responses
width?	integer	The width of the media item — provided by the API in responses
content_type?	string	The media type of the content — provided by the API in responses
attachment_id?*	snowflake	The ID of the uploaded attachment — provided by the API in responses

* Only present if the media item was uploaded as an attachment.

Uploading a File

To upload a file with your message, send your payload as multipart/form-data (rather than application/json) and include your file with a valid filename. Details and examples can be found in the API Reference.

Legacy Message Component Behavior

Before the introduction of the IS_COMPONENTS_V2 flag, message components were sent in conjunction with message content. You could send a message using a subset of available components without setting the flag, and components would be included alongside content and embeds. Components in legacy messages will contain an id of 0. Apps using legacy behavior will continue to work as expected, but using the IS_COMPONENTS_V2 flag is recommended for new apps and features as it offers more options for layout and customization.

Legacy messages allow up to 5 action rows as top-level components.

{
  "content": "This is a message with legacy components",
  "components": [
    {
      "type": 1,
      "components": [
        {
          "type": 2,
          "style": 1,
          "label": "Click Me",
          "custom_id": "click_me_1"
        }
      ]
    }
  ]
}

Introduction

Platform Overview

Bots & Interactions

Monetization & Discovery

Policies

Layout Components

Content Components

Interactive Components

What is a Component

Component Types

Anatomy of a Component

Custom ID

Action Row

Button

Button Design Guidelines

String Select

Text Input

User Select

Role Select

Mentionable Select

Channel Select

Section

Text Display

Thumbnail

Media Gallery

File

Separator

Container

Label

File Upload

Radio Group

Checkbox Group

Checkbox

Unfurled Media Item

Uploading a File

Legacy Message Component Behavior

Introduction

Platform Overview

Bots & Interactions

Monetization & Discovery

Policies

Layout Components

Content Components

Interactive Components

​What is a Component

​Component Types

​Anatomy of a Component

​Custom ID

​Action Row

​Button

​Button Design Guidelines

​String Select

​Text Input

​User Select

​Role Select

​Mentionable Select

​Channel Select

​Section

​Text Display

​Thumbnail

​Media Gallery

​File

​Separator

​Container

​Label

​File Upload

​Radio Group

​Checkbox Group

​Checkbox

​Unfurled Media Item

​Uploading a File

​Legacy Message Component Behavior

What is a Component

Component Types

Anatomy of a Component

Custom ID

Action Row

Button

Button Design Guidelines

String Select

Text Input

User Select

Role Select

Mentionable Select

Channel Select

Section

Text Display

Thumbnail

Media Gallery

File

Separator

Container

Label

File Upload

Radio Group

Checkbox Group

Checkbox

Unfurled Media Item

Uploading a File

Legacy Message Component Behavior