Components

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)
• Content Components - For displaying static text, images, and files (Text Display, Media Gallery, Thumbnails)
• Interactive Components - For user interactions (Buttons, Select Menus, Text Input)

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

• The content and embeds fields will no longer work, but you'll be able to 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
• The combined length of all text across all components cannot exceed 4000 characters

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 integrations.

Components are a field on the message object and in modals. You can use them when creating messages or responding to an interaction, like an application command.

Legacy Message Component Behavior

Before the introduction of the IS_COMPONENTS_V2 flag, message components were sent in conjunction with message content. This means that you could send a message using a subset of the available components without setting the IS_COMPONENTS_V2 flag, and the components would be included in the message content along with content and embeds.

Additionally, components of messages preceding components v2 will contain an id of 0.

Component Object

Component Type

¹ Requires the IS_COMPONENTS_V2 message flag.

² Not usable by bots.

Anatomy of a Component

All components have the following fields:

The id field is optional and is used to identify components in the response from an interaction that aren't interactive components. 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 a maximum of 100 characters and can be used flexibly to maintain state or pass through other important data.

Action Row

An Action Row is a top-level layout component used in messages and modals.

Action Rows can contain:

• Up to 5 contextually grouped buttons
• A single select component (string select, user select, role select, mentionable select, or channel select)
• A single text input (in modals)

Action Row Structure

Example Action Row

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

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

Buttons come in various styles to convey different types of actions. These styles also define what fields are valid for a button.

• Non-link and non-premium buttons must have a custom_id, and cannot have a url or a sku_id.
• Link buttons must have a url, and cannot have a custom_id
• Link buttons do not send an interaction to your app when clicked
• Premium buttons must contain a sku_id, and cannot have a custom_id, label, url, or emoji.
• Premium buttons do not send an interaction to your app when clicked

Button Style

Example Button

{
  "type": 1,
  "components": [
    {
      "type": 2,
      "label": "Click me!",
      "style": 1,
      "custom_id": "clicked_me"
    }
  ]
}

Button Design Guidelines

General Button Content

• 34 characters max with icon or emoji.
• 38 characters max without icon or emoji.

Premium Buttons

Premium buttons will automatically have the following:

• Shop icon
• SKU name
• SKU price

String Select

A String Select is an interactive component that allows users to select one or more provided options in a message.

String Selects can be configured for 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

¹ Only applicable within modals.

² Cannot be set in modals.

Select Option Structure

Example String Select

{
  "type": 3,
  "custom_id": "string_select",
  "placeholder": "Favorite bug?",
  "options": [
    {
      "label": "Ant",
      "value": "ant",
      "description": "(best option)",
      "emoji": { "name": "🐜" }
    },
    {
      "label": "Butterfly",
      "value": "butterfly",
      "emoji": { "name": "🦋" }
    },
    {
      "label": "Catarpillar",
      "value": "caterpillar",
      "emoji": { "name": "🐛" }
    }
  ]
}

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 an Action Row or a Label.

Text Input Structure

¹ Ignored within a Label in favor of its label and description fields.

Text Input Style

Example Text Input

{
  "type": 1,
  "components": [
    {
      "type": 4,
      "custom_id": "name",
      "label": "Name",
      "style": 1,
      "min_length": 1,
      "max_length": 4000,
      "placeholder": "John",
      "required": true
    }
  ]
}

User Select

A User Select is an interactive component that allows users to select one or more users in a message. Options are automatically populated based on the guild's available users.

User Selects can be configured for both single-select and multi-select behavior. When a user finishes making their choice(s) your app receives an interaction.

User Selects are available in messages and modals. They must be placed inside an Action Row in messages and a Label in modals.

User Select Structure

¹ Only applicable within modals.

² Cannot be set in modals.

Select Default Value Structure

Example User Select

{
  "type": 1,
  "components": [
    {
      "type": 5,
      "custom_id": "user_select",
      "placeholder": "Select a user"
    }
  ]
}

Role Select

A Role Select is an interactive component that allows users to select one or more roles in a message. Options are automatically populated based on the guild's available roles.

Role Selects can be configured for both single-select and multi-select behavior. When a user finishes making their choice(s) your app receives an interaction.

Role Selects are available in messages and modals. They must be placed inside an Action Row in messages and a Label in modals.

Role Select Structure

¹ Only applicable within modals.

² Cannot be set in modals.

Example Role Select

{
  "type": 1,
  "components": [
    {
      "type": 6,
      "custom_id": "role_select",
      "placeholder": "Which roles?",
      "min_values": 1,
      "max_values": 3
    }
  ]
}

Mentionable Select

A Mentionable Select is an interactive component that allows users to select one or more mentionables in a message. Options are automatically populated based on available mentionables in the guild.

Mentionable Selects can be configured for both single-select and multi-select behavior. When a user finishes making their choice(s), your app receives an interaction.

Mentionable Selects are available in messages and modals. They must be placed inside an Action Row in messages and a Label in modals.

Mentionable Select Structure

¹ Only applicable within modals.

² Cannot be set in modals.

Example Mentionable Select

{
  "type": 1,
  "components": [
    {
      "type": 7,
      "custom_id": "mentionable_select",
      "placeholder": "Who?"
    }
  ]
}

Channel Select

A Channel Select is an interactive component that allows users to select one or more channels in a message. Options are automatically populated based on available channels in the guild and can be filtered by channel types.

Channel Selects can be configured for both single-select and multi-select behavior. When a user finishes making their choice(s) your app receives an interaction.

Channel Selects are available in messages and modals. They must be placed inside an Action Row in messages and a Label in modals.

Channel Select Structure

¹ Only applicable within modals.

² Cannot be set in modals.

Example Channel Select

{
  "type": 1,
  "components": [
    {
      "type": 8,
      "custom_id": "channel_select",
      "channel_types": [0],
      "placeholder": "Which text channel?"
    }
  ]
}

Section

A Section is a top-level layout component that allows you to join text contextually with an accessory.

Sections are only available in messages.

Section Structure

¹ May be expanded to include other component types in the future.

Example Section

{
  "type": 9,
  "components": [
    {
      "type": 10,
      "content": "# Real Game v7.3"
    },
    {
      "type": 10,
      "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\n- Every third thursday the furniture will scream your darkest secrets to nearby npcs"
    },
    {
      "type": 10,
      "content": "-# That last one wasn't real, but don't use voice chat near furniture just in case..."
    }
  ],
  "accessory": {
    "type": 11,
    "media": {
      "url": "https://websitewithopensourceimages/gamepreview.png"
    }
  }
}

Text Display

A Text Display is a top-level content component that allows you to add markdown formatted text, including mentions (users, roles, etc) and emoji. The behavior of this component is extremely similar to the content field of a message, but allows you to add multiple text components, controlling the layout of your message.

When sent in a message, mentions (@user, @role, etc.) present in this component will ping and send notifications based on the value of allowed_mentions in the message.

Text Display Structure

Thumbnail

A Thumbnail is a content component that is a small image only usable as an accessory in a section. The preview comes from an url or attachment through the unfurled media item structure.

Thumbnails are only available in messages as an accessory in a section.

Thumbnail Structure

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.

Media Gallery Structure

Media Gallery Item Structure

Example Media Gallery

{
  "type": 12,
  "items": [
    {
      "media": { "url": "https://livevideofeedconvertedtoimage/webcam1.png" },
      "description": "An aerial view looking down on older industrial complex buildings. The main building is white with many windows and pipes running up the walls."
    },
    {
      "media": { "url": "https://livevideofeedconvertedtoimage/webcam2.png" },
      "description": "An aerial view of old broken buildings. Nature has begun to take root in the rooftops. A portion of the middle building's roof has collapsed inward. In the distant haze you can make out a far away city."
    },
    {
      "media": { "url": "https://livevideofeedconvertedtoimage/webcam3.png" },
      "description": "A street view of a downtown city. Prominently in photo are skyscrapers and a domed building"
    }
  ]
}

File

A File is a top-level component that allows you to display an uploaded file as an attachment to the message and reference it in the component. 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.

Files are only available in messages.

File Structure

¹ This field is received only and cannot be set.

Example File Component

{
  "type": 13,
  "file": {
    "url": "attachment://game.zip"
  }
}

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.

Separator Structure

Separator Spacing Type

Example Separator

{
  "type": 14,
  "divider": true,
  "spacing": 1
}

Content Inventory Entry

A Content Inventory Entry is a top-level component that displays an activity feed entry.

Content Inventory Entries cannot be sent directly.

Content Inventory Entry Structure

Content Inventory Entry Object

Content Inventory Author Type

Content Inventory Content Type

Content Inventory Trait Object

Content Inventory Trait Type

Content Inventory Aggregate Range Type

Content Inventory Trending Type

Content Inventory Metadata Object

Content Inventory Metadata Type

Content Inventory Provider Type

Content Inventory Media Type

Content Inventory Metadata Entry Object

Content Inventory Artist Object

Content Inventory Platform Type

Content Inventory Signature Object

Example Content Inventory Entry

{
  "type": 16,
  "id": "0",
  "content_inventory_entry": {
    "author_id": "150745989836308480",
    "author_type": 1,
    "content_type": 1,
    "ended_at": "2025-04-23T02:13:18.123000+00:00",
    "extra": {
      "application_id": "356879032584896512",
      "game_name": "Garry's Mod",
      "platform": 0,
      "type": "played_game_extra"
    },
    "id": "1364423860543557746",
    "participants": ["150745989836308480"],
    "signature": {
      "kid": "AtDT4Kx25Wmu5cfllPxAiwZKgPbmLsaeHitpx/duvPY=",
      "signature": "580e54d406bc466a936cbd9a1b8f19954997187d56638c84871cc5f3cd9c245b",
      "version": 1
    },
    "started_at": "2025-04-23T02:11:24.123000+00:00",
    "traits": [
      {
        "duration_seconds": 114,
        "type": 2
      },
      {
        "streak_count_days": 3,
        "type": 8
      }
    ]
  }
}

Container

A Container is a top-level layout component that holds up to 10 components. Containers are visually distinct from surrounding components and have an optional customizable color bar.

Containers are only available in messages.

Container Structure

Example Container

{
  "type": 17,
  "accent_color": 703487,
  "components": [
    {
      "type": 10,
      "content": "# You have encountered a wild coyote!"
    },
    {
      "type": 12,
      "items": [
        {
          "media": { "url": "https://websitewithopensourceimages/coyote.png" }
        }
      ]
    },
    {
      "type": 10,
      "content": "What would you like to do?"
    },
    {
      "type": 1,
      "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. Labels wrap modal components with text as a label and optional description.

Label Structure

File Upload

File Upload is an interactive component that allows users to upload up to 10 files in modals.

File Uploads can only be used within modals and must be placed inside a Label.

File Upload Structure

Checkpoint Card

A Checkpoint Card is a top-level component that displays a summary of the user's checkpoint.

Checkpoint cards cannot be sent directly.

Checkpoint Card Structure

Checkpoint Data Structure

Checkpoint Card Guild Structure

Checkpoint Card Emoji Structure

Checkpoint Card Game Structure

Example Checkpoint Card

{
  "type": 20,
  "id": 1,
  "checkpoint_data": {
    "version": 0,
    "num_messages_sent": 53146,
    "total_voice_minutes": 6.3231166666666665,
    "num_emojis_sent": 13096,
    "top_emoji": {
      "emoji_id": "1145727546747535412",
      "emoji_name": "blobcatcozy"
    },
    "top_guild": {
      "guild_id": "1046920999469330512",
      "guild_name": "Alien Network",
      "guild_icon": "66b0f4d96c145970fa9d96ada8afadf3"
    },
    "top_game": {
      "application_id": "363445589247131668",
      "application_name": "Roblox",
      "application_image_id": "f2b60e350a2097289b3b0b877495e55f"
    },
    "card_id": 5,
    "power_level": 83732.32311666667,
    "power_level_percentile": 96.71
  }
}

Radio Group

Radio Group is an interactive component for selecting exactly one option from a defined list.

Radio Groups can only be used within modals and must be placed inside a Label.

Radio Group Structure

Radio Group Option Structure

Checkbox Group

Checkbox Group is an interactive component for selecting one or many options via checkboxes.

Checkbox Groups can only be used within modals and must be placed inside a Label.

Checkbox Group Structure

Checkbox Group Option Structure

Checkbox

Checkbox is a single interactive component for simple yes/no style questions.

Checkboxes can only be used within modals and must be placed inside a Label.

Checkbox Structure

Unfurled Media Item Object

Unfurled Media Item Object Structure

¹ This field is received only and cannot be set.

Unfurled Media Item Loading State