Bot UI Kit

The library implements a UI Kit that allows you to create interactive components for your Discord applications.

API Models

Attributes
Methods
class discord.components.ActionRow(*components, id=None)[source]

Represents a Discord Bot UI Kit Action Row.

This is a component that holds up to 5 children components in a row.

This inherits from Component.

Added in version 2.0.

Changed in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.action_row]

components

The components that this ActionRow holds, if any.

Type:

list[AllowedActionRowComponents]

id

The action row’s ID. If not provided, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

Type:

int | None

Parameters:
property width

Return the sum of the components’ widths.

any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

get_by_id(component_id)

Gets a component by its ID or custom ID.

Parameters:

component_id (str | int) – The ID (int) or custom ID (str) of the component to get.

Returns:

The children component with the given ID or custom ID, or None if not found.

Return type:

AllowedComponents | None

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Attributes
Methods
class discord.components.Button(style: Literal[ButtonStyle.premium], *, sku_id: int, disabled: bool = False, id: int | None = None)[source]
class discord.components.Button(style: Literal[ButtonStyle.link], *, label: str, emoji: str | AnyEmoji | None = None, disabled: bool = False, url: str, id: int | None = None)
class discord.components.Button(style: Literal[ButtonStyle.link], *, emoji: str | AnyEmoji, label: str | None = None, disabled: bool = False, url: str, id: int | None = None)
class discord.components.Button(style: Literal[ButtonStyle.primary, ButtonStyle.secondary, ButtonStyle.success, ButtonStyle.danger], *, custom_id: str, label: str, emoji: str | AnyEmoji | None = None, disabled: bool = False, id: int | None = None)
class discord.components.Button(style: Literal[ButtonStyle.primary, ButtonStyle.secondary, ButtonStyle.success, ButtonStyle.danger], *, custom_id: str, emoji: str | AnyEmoji, label: str | None = None, disabled: bool = False, id: int | None = None)

Represents a button from the Discord Bot UI Kit.

This inherits from Component.

Added in version 2.0.

type

The type of component.

Type:

Literal[ComponentType.button]

style

The style of the button.

Type:

ButtonStyle

custom_id

The ID of the button that gets received during an interaction. If this button is for a URL, it does not have a custom ID.

Type:

str | None

url

The URL this button sends you to.

Type:

str | None

disabled

Whether the button is disabled or not.

Type:

bool

label

The label of the button, if any.

Type:

str | None

emoji

The emoji of the button, if available.

Type:

PartialEmoji] | None

sku_id

The ID of the SKU this button refers to.

Type:

int | None

id

The button’s ID. If not provided, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

Type:

int | None

Parameters:

  • style (int | ButtonStyle) – The style of the button.

  • custom_id (str | None) – The ID of the button that gets received during an interaction. Cannot be used with ButtonStyle.url or ButtonStyle.premium.

  • label (str | None) – The label of the button, if any. Cannot be used with ButtonStyle.premium.

  • emoji (str | AnyEmoji | None) – The emoji of the button, if available. Cannot be used with ButtonStyle.premium.

  • disabled (bool) – Whether the button is disabled or not.

  • url (str | None) – The URL this button sends you to. Can only be used with ButtonStyle.url.

  • id (int | None) – The button’s ID. If not provided, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

  • sku_id (int | None) – The ID of the SKU this button refers to. Can only be used with ButtonStyle.premium.

any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Attributes
Methods
class discord.components.StringSelect(custom_id, options, *, placeholder=None, min_values=1, max_values=1, disabled=False, id=None, required=True)[source]

Represents a string select menu from the Discord Bot UI Kit.

This inherits from SelectMenu.

Added in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.string_select]

options

The options available in this select menu.

Type:

List[SelectOption]

custom_id

The custom ID of the select menu that gets received during an interaction.

Type:

str

placeholder

The placeholder text that is shown if nothing is selected, if any.

Type:

Optional[str]

min_values

The minimum number of values that must be selected. Defaults to 1.

Type:

int

max_values

The maximum number of values that can be selected. Defaults to 1.

Type:

int

disabled

Whether the select menu is disabled or not. Defaults to False.

Type:

bool

id

The string select menu’s ID.

Type:

int | None

required

Whether the string select is required or not. Only applicable when used in a discord.Modal.

Type:

bool

Parameters:

  • custom_id (str) – The custom ID of the select menu that gets received during an interaction.

  • options (Sequence[SelectOption]) – The options available in this select menu.

  • placeholder (str | None) – The placeholder text that is shown if nothing is selected, if any.

  • min_values (int) – The minimum number of values that must be selected. Defaults to 1.

  • max_values (int) – The maximum number of values that can be selected. Defaults to 1.

  • disabled (bool) – Whether the select menu is disabled or not. Defaults to False.

  • id (int | None) – The string select menu’s ID. If not provided, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

  • required (bool) – Whether the string select is required or not. Defaults to True. Only applicable when used in a discord.Modal.

any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Attributes
Methods
class discord.components.TextInput(style, custom_id, min_length=None, max_length=None, placeholder=None, required=True, value=None, id=None)[source]

Represents an Input Text field from the Discord Bot UI Kit.

This inherits from Component.

Changed in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.input_text]

style

The style of the input text field.

Type:

TextInputStyle

custom_id

The custom ID of the input text field that gets received during an interaction.

Type:

str | None

placeholder

The placeholder text that is shown if nothing is selected, if any.

Type:

class:str | None

min_length

The minimum number of characters that must be entered Defaults to 0

Type:

int | None

max_length

The maximum number of characters that can be entered

Type:

int | None

required

Whether the input text field is required or not. Defaults to True.

Type:

bool | None

value

The value that has been entered in the input text field.

Type:

str | None

id

The input text’s ID.

Type:

int | None

Parameters:

  • style (TextInputStyle) – The style of the input text field.

  • custom_id (str) – The custom ID of the input text field that gets received during an interaction.

  • min_length (int | None) – The minimum number of characters that must be entered. Defaults to 0.

  • max_length (int | None) – The maximum number of characters that can be entered.

  • placeholder (str | None) – The placeholder text that is shown if nothing is selected, if any.

  • required (bool) – Whether the input text field is required or not. Defaults to True.

  • value (str | None) – The value that has been entered in the input text field.

  • id (int | None) – The input text’s ID. If not provided, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Attributes
Methods
class discord.components.UserSelect(*, default_values=None, custom_id, placeholder=None, min_values=1, max_values=1, disabled=False, id=None, required=True)[source]

Represents a user select menu from the Discord Bot UI Kit.

This inherits from SelectMenu.

Added in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.user_select]

default_values

The default selected values of the select menu.

Type:

List[DefaultSelectOption]

custom_id

The custom ID of the select menu that gets received during an interaction.

Type:

str

placeholder

The placeholder text that is shown if nothing is selected, if any.

Type:

str | None

min_values

The minimum number of values that must be selected.

Type:

int

max_values

The maximum number of values that can be selected.

Type:

int

disabled

Whether the select menu is disabled or not.

Type:

bool

id

The user select menu’s ID.

Type:

int | None

required

Whether the user select is required or not. Only applicable when used in a discord.Modal.

Type:

bool

Parameters:

  • default_values (Sequence[DefaultSelectOption[Literal['user']]] | None) – The default selected values of the select menu.

  • custom_id (str) – The custom ID of the select menu that gets received during an interaction.

  • options – The options available in this select menu.

  • placeholder (str | None) – The placeholder text that is shown if nothing is selected, if any.

  • min_values (int) – The minimum number of values that must be selected. Defaults to 1.

  • max_values (int) – The maximum number of values that can be selected. Defaults to 1.

  • disabled (bool) – Whether the select menu is disabled or not. Defaults to False.

  • id (int | None) – The user select menu’s ID. If not provided, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

  • required (bool) – Whether the user select is required or not. Defaults to True. Only applicable when used in a discord.Modal.

any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Attributes
Methods
class discord.components.RoleSelect(*, default_values=None, custom_id, placeholder=None, min_values=1, max_values=1, disabled=False, id=None, required=True)[source]

Represents a role select menu from the Discord Bot UI Kit.

This inherits from SelectMenu.

Added in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.role_select]

default_values

The default selected values of the select menu.

Type:

List[DefaultSelectOption]

custom_id

The custom ID of the select menu that gets received during an interaction.

Type:

str

placeholder

The placeholder text that is shown if nothing is selected, if any.

Type:

Optional[str]

min_values

The minimum number of values that must be selected. Defaults to 1.

Type:

int

max_values

The maximum number of values that can be selected. Defaults to 1.

Type:

int

disabled

Whether the select menu is disabled or not. Defaults to False.

Type:

bool

id

The role select menu’s ID.

Type:

int | None

required

Whether the role select is required or not. Only applicable when used in a discord.Modal.

Type:

bool

Parameters:

  • default_values (Sequence[DefaultSelectOption[Literal['role']]] | None) – The default selected values of the select menu.

  • custom_id (str) – The custom ID of the select menu that gets received during an interaction.

  • placeholder (str | None) – The placeholder text that is shown if nothing is selected, if any.

  • min_values (int) – The minimum number of values that must be selected. Defaults to 1.

  • max_values (int) – The maximum number of values that can be selected. Defaults to 1.

  • disabled (bool) – Whether the select menu is disabled or not. Defaults to False.

  • id (int | None) – The select menu’s ID. If not provided, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

  • required (bool) – Whether the role select is required or not. Defaults to True. Only applicable when used in a discord.Modal.

any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Attributes
Methods
class discord.components.MentionableSelect(*, default_values=None, custom_id, placeholder=None, min_values=1, max_values=1, disabled=False, id=None, required=True)[source]

Represents a mentionable select menu from the Discord Bot UI Kit.

This inherits from SelectMenu.

Added in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.mentionable_select]

default_values

The default selected values of the select menu.

Type:

List[DefaultSelectOption]

custom_id

The custom ID of the select menu that gets received during an interaction.

Type:

str

placeholder

The placeholder text that is shown if nothing is selected, if any.

Type:

str | None

min_values

The minimum number of values that must be selected.

Type:

int

max_values

The maximum number of values that can be selected.

Type:

int

disabled

Whether the select menu is disabled or not.

Type:

bool

id

The mentionable select menu’s ID.

Type:

int | None

required

Whether the mentionable select is required or not. Only applicable when used in a discord.Modal.

Type:

bool

Parameters:

  • default_values (Sequence[DefaultSelectOption[Literal['role', 'user']]] | None) – The default selected values of the select menu.

  • custom_id (str) – The custom ID of the select menu that gets received during an interaction.

  • placeholder (str | None) – The placeholder text that is shown if nothing is selected, if any.

  • min_values (int) – The minimum number of values that must be selected. Defaults to 1.

  • max_values (int) – The maximum number of values that can be selected. Defaults to 1.

  • disabled (bool) – Whether the select menu is disabled or not. Defaults to False.

  • id (int | None) – The mentionable select menu’s ID. If not provided, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

  • required (bool) – Whether the mentionable select is required or not. Defaults to True. Only applicable when used in a discord.Modal.

any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Attributes
Methods
class discord.components.ChannelSelect(*, default_values=None, custom_id, placeholder=None, min_values=1, max_values=1, disabled=False, id=None, required=True)[source]

Represents a channel select menu from the Discord Bot UI Kit.

This inherits from SelectMenu.

Added in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.channel_select]

default_values

The default selected values of the select menu.

Type:

List[DefaultSelectOption]

custom_id

The custom ID of the select menu that gets received during an interaction.

Type:

str

placeholder

The placeholder text that is shown if nothing is selected, if any.

Type:

str | None

min_values

The minimum number of values that must be selected. Defaults to 1.

Type:

int

max_values

The maximum number of values that can be selected. Defaults to 1.

Type:

int

disabled

Whether the select menu is disabled or not. Defaults to False.

Type:

bool

id

The channel select menu’s ID.

Type:

int | None

required

Whether the channel select is required or not. Only applicable when used in a discord.Modal.

Type:

bool

Parameters:

  • default_values (Sequence[DefaultSelectOption[Literal['channel']]] | None) – The default selected values of the select menu.

  • custom_id (str) – The custom ID of the select menu that gets received during an interaction.

  • placeholder (str | None) – The placeholder text that is shown if nothing is selected, if any.

  • min_values (int) – The minimum number of values that must be selected. Defaults to 1.

  • max_values (int) – The maximum number of values that can be selected. Defaults to 1.

  • disabled (bool) – Whether the select menu is disabled or not. Defaults to False.

  • id (int | None) – The select menu’s ID. If not provided, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

  • required (bool) – Whether the channel select is required or not. Defaults to True. Only applicable when used in a discord.Modal.

any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Attributes
Methods
class discord.components.Section(components, accessory=None, id=None)[source]

Represents a Section from Components V2.

This is a component that groups other components together with an additional component to the right as the accessory.

This inherits from Component.

Added in version 2.7.

type

The type of component.

Type:

Literal[ComponentType.section]

components

The components contained in this section. Currently supports TextDisplay.

Type:

List[Component]

accessory

The accessory attached to this Section. Currently supports Button and Thumbnail.

Type:

Component | None

id

The section’s ID.

Type:

int | None

Parameters:

  • components (Sequence[TextDisplay]) – The components contained in this section. Currently supports TextDisplay.

  • accessory (Button | Thumbnail | None) – The accessory attached to this Section. Currently supports Button and Thumbnail.

  • id (int | None) – The section’s ID. If not provided, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

get_by_id(component_id)

Gets a component by its ID or custom ID.

Parameters:

component_id (str | int) – The ID (int) or custom ID (str) of the component to get.

Returns:

The children component with the given ID or custom ID, or None if not found.

Return type:

AllowedComponents | None

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Attributes
Methods
class discord.components.TextDisplay(content, id=None)[source]

Represents a Text Display from Components V2.

This is a component that displays text.

This inherits from Component.

Added in version 2.7.

Changed in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.text_display]

content

The component’s text content.

Type:

str

id

The text display’s ID.

Type:

int | None

Parameters:

  • content (str) – The text content of the component. Can be markdown formatted.

  • id (int | None) – The text display’s ID. If not provided, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Attributes
Methods
class discord.components.Thumbnail(url, *, id=None, description=None, spoiler=False)[source]

Represents a Thumbnail from Components V2.

This is a component that displays media, such as images and videos.

This inherits from Component.

Added in version 2.7.

Changed in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.thumbnail]

media

The component’s underlying media object.

Type:

UnfurledMediaItem

description

The thumbnail’s description, up to 1024 characters.

Type:

str | None

spoiler

Whether the thumbnail has the spoiler overlay.

Type:

bool | None

id

The thumbnail’s ID.

Type:

int | None

Parameters:

  • url (str | UnfurledMediaItem) – The URL of the thumbnail. This can either be an arbitrary URL or an attachment:// URL to work with local files.

  • id (int | None) – The thumbnail’s ID. If not provided, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

  • description (str | None) – The thumbnail’s description, up to 1024 characters.

  • spoiler (bool | None) – Whether the thumbnail has the spoiler overlay. Defaults to False.

property url: str

Returns the URL of this thumbnail’s underlying media item.

any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Attributes
Methods
class discord.components.MediaGallery(*items, id=None)[source]

Represents a Media Gallery from Components V2.

This is a component that displays up to 10 different MediaGalleryItem objects.

This inherits from Component.

Added in version 2.7.

Changed in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.media_gallery]

items

The media this gallery contains.

Type:

List[MediaGalleryItem]

id

The media gallery’s ID.

Type:

int | None

Parameters:

  • items (MediaGalleryItem) – The media gallery items this gallery contains. Has to be passed unpacked (e.g. *items).

  • id (int | None) – The component’s ID. If not provided by the user, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Attributes
Methods
class discord.components.FileComponent(url, *, spoiler=False, id=None, size=None, name=None)[source]

Represents a File from Components V2.

This component displays a downloadable file in a message.

This inherits from Component.

Added in version 2.7.

Changed in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.file]

file

The file’s media item.

Type:

UnfurledMediaItem

name

The file’s name.

Type:

str

size

The file’s size in bytes.

Type:

int

spoiler

Whether the file has the spoiler overlay.

Type:

bool | None

Parameters:

  • url (str) – The URL of this media gallery item. This HAS to be an attachment:// URL to work with local files.

  • spoiler (bool | None) – Whether the file has the spoiler overlay. Defaults to False.

  • id (int | None) – The component’s ID. If not provided by the user, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

  • size (int | None) – The file’s size in bytes. If not provided, it is set to None.

  • name (str | None) – The file’s name. If not provided, it is set to None.

any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Attributes
Methods
class discord.components.Separator(divider=True, spacing=SeparatorSpacingSize.small, id=None)[source]

Represents a Separator from Components V2.

This is a component that visually separates components.

This inherits from Component.

Added in version 2.7.

Changed in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.separator]

divider

Whether the separator will show a horizontal line in addition to vertical spacing.

Type:

bool

spacing

The separator’s spacing size.

Type:

SeparatorSpacingSize | None

id

The separator’s ID.

Type:

int | None

Parameters:

  • divider (bool) – Whether the separator will show a horizontal line in addition to vertical spacing. Defaults to True.

  • spacing (SeparatorSpacingSize) – The separator’s spacing size. Defaults to SeparatorSpacingSize.small.

  • id (int | None) – The separator’s ID. If not provided by the user, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Attributes
Methods
class discord.components.Container(*components, accent_color=None, spoiler=False, id=None)[source]

Represents a Container from Components V2.

This is a component that contains different Component objects. It may only contain:

This inherits from Component.

Added in version 2.7.

Changed in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.container]

components

The components contained in this container.

Type:

List[AllowedContainerComponents]

accent_color

The accent color of the container.

Type:

Colour | None

spoiler

Whether the entire container has a spoiler overlay.

Type:

bool | None

id

The container’s ID.

Type:

int | None

Parameters:

  • components (ActionRow | TextDisplay | Section | MediaGallery | Separator | FileComponent) – The components to include in this container. Has to be passed unpacked (e.g. *components).

  • accent_color (Colour | None) – The accent color of the container. If not provided, it defaults to None.

  • spoiler (bool | None) – Whether the entire container has the spoiler overlay. If not provided, it defaults to False.

  • id (int | None) – The container’s ID. If not provided, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

get_by_id(component_id)

Gets a component by its ID or custom ID.

Parameters:

component_id (str | int) – The ID (int) or custom ID (str) of the component to get.

Returns:

The children component with the given ID or custom ID, or None if not found.

Return type:

AllowedComponents | None

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Attributes
Methods
class discord.components.Label(component, label, description=None, id=None)[source]

Represents a Label component.

This is a component used exclusively within a Modal to hold InputText components.

This inherits from Component.

Added in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.label]

component

The components contained in this label.

Type:

list of Component

label

The text of the label.

Type:

str

description

The description of the label.

Type:

str | None

id

The label’s ID.

Type:

int | None

Parameters:
any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

get_by_id(component_id)

Gets a component by its ID or custom ID.

Parameters:

component_id (str | int) – The ID (int) or custom ID (str) of the component to get.

Returns:

The children component with the given ID or custom ID, or None if not found.

Return type:

AllowedComponents | None

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Interaction Components

These objects are dataclasses that represent components as they are received from Discord in interaction payloads, currently applicable only with discord.components.Interaction of type discord.components.InteractionType.modal_submit.

Attributes
class discord.components.PartialLabel(id, component, *, type=ComponentType.label)[source]

Represents a Label component as returned by Discord during a Interaction of type InteractionType.modal_submit.

This is a component used exclusively within a Modal to hold other components.

Added in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.label]

component

The component contained in this label.

Type:

PartialTextInput | PartialStringSelect

id

The ID of this label component.

Type:

int

Parameters:

  • id (int)

  • component (TypeVar(L_c, bound= PartialStringSelect | PartialUserSelect | PartialChannelSelect | PartialRoleSelect | PartialMentionableSelect | PartialTextInput | PartialFileUpload))

  • type (Literal[<ComponentType.label: 18>])

Attributes
class discord.components.PartialStringSelect(id, custom_id, values, *, type=ComponentType.string_select)[source]

Represents a StringSelect component as returned by Discord during a Interaction of type InteractionType.modal_submit.

Added in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.string_select]

values

The values selected in the string select menu.

Type:

list of str

id

The ID of this string select menu component.

Type:

int

custom_id

The custom ID of this string select menu component.

Type:

str

Parameters:
Attributes
class discord.components.PartialUserSelect(id, custom_id, values, *, type=ComponentType.user_select)[source]

Represents a UserSelect component as returned by Discord during a Interaction of type InteractionType.modal_submit.

Added in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.user_select]

values

The user IDs selected in the user select menu.

Type:

list of int

id

The ID of this user select menu component.

Type:

int

custom_id

The custom ID of this user select menu component.

Type:

str

Parameters:
Attributes
class discord.components.PartialRoleSelect(id, custom_id, values, *, type=ComponentType.role_select)[source]

Represents a RoleSelect component as returned by Discord during a Interaction of type InteractionType.modal_submit.

Added in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.role_select]

values

The role IDs selected in the role select menu.

Type:

list of int

id

The ID of this role select menu component.

Type:

int

custom_id

The custom ID of this role select menu component.

Type:

str

Parameters:
Attributes
class discord.components.PartialMentionableSelect(id, custom_id, values, *, type=ComponentType.mentionable_select)[source]

Represents a MentionableSelect component as returned by Discord during a Interaction of type InteractionType.modal_submit.

Added in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.mentionable_select]

values

The IDs selected in the mentionable select menu.

Type:

list of int

id

The ID of this mentionable select menu component.

Type:

int

custom_id

The custom ID of this mentionable select menu component.

Type:

str

Parameters:

  • id (int)

  • custom_id (str)

  • values (list[TypeVar(V, bound= str | int)])

  • type (Literal[<ComponentType.mentionable_select: 7>])

Attributes
class discord.components.PartialChannelSelect(id, custom_id, values, *, type=ComponentType.channel_select)[source]

Represents a ChannelSelect component as returned by Discord during a Interaction of type InteractionType.modal_submit.

Added in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.channel_select]

values

The channel IDs selected in the channel select menu.

Type:

list of int

id

The ID of this channel select menu component.

Type:

int

custom_id

The custom ID of this channel select menu component.

Type:

str

Parameters:

  • id (int)

  • custom_id (str)

  • values (list[TypeVar(V, bound= str | int)])

  • type (Literal[<ComponentType.channel_select: 8>])

Attributes
class discord.components.PartialTextInput(id, custom_id, value, *, type=ComponentType.text_input)[source]

Represents a TextInput component as returned by Discord during a Interaction of type InteractionType.modal_submit.

Added in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.text_input]

value

The value of the text input.

Type:

str

id

The ID of this text input component.

Type:

int

custom_id

The custom ID of this text input component.

Type:

str

Parameters:

  • id (int)

  • custom_id (str)

  • value (str)

  • type (Literal[<ComponentType.text_input: 4>])

Attributes
class discord.components.PartialTextDisplay(id, *, type=ComponentType.text_display)[source]

Represents a TextDisplay component as returned by Discord during a Interaction of type InteractionType.modal_submit.

Added in version 3.0.

type

The type of component.

Type:

Literal[ComponentType.text_display]

id

The ID of this text display component.

Type:

int

Parameters:

  • id (int)

  • type (Literal[<ComponentType.text_display: 10>])

Additional Objects

Attributes
class discord.components.Modal(*components, title, custom_id)[source]

Represents a modal. Used when sending modals with InteractionResponse.send_modal()

..versionadded:: 3.0

title

The title of the modal. This is shown at the top of the modal.

Type:

str

custom_id

The custom ID of the modal. This is received during an interaction.

Type:

str

components

The components in the modal.

Type:

List[Label | TextDisplay]

Parameters:

  • components (Label | TextDisplay) – The components this modal holds. Has to be passed unpacked (e.g. *components).

  • title (str) – The title of the modal. This is shown at the top of the modal.

  • custom_id (str) – The custom ID of the modal. This is received during an interaction.

Attributes
Methods
class discord.components.UnknownComponent(type, id=None)[source]

Represents an unknown component.

This is used when the component type is not recognized by the library, for example if a new component is introduced by Discord.

Added in version 3.0.

type

The type of the unknown component.

Type:

ComponentType

id

The component’s ID.

Type:

int | None

Parameters:

  • type (ComponentType)

  • id (int | None)

any_is_dispatchable()

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

any_is_v2()

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

is_dispatchable()

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

is_v2()

Whether this component was introduced in Components V2.

Return type:

bool

Attributes
Methods
class discord.components.UnfurledMediaItem(url)[source]

Represents an Unfurled Media Item used in Components V2.

This is used as an underlying component for other media-based components such as Thumbnail, FileComponent, and MediaGalleryItem.

This should normally not be created directly.

Added in version 2.7.

Parameters:

url (str)

property url: str

Returns this media item’s url.

await read()

This function is a coroutine.

Retrieves the content of this asset as a bytes object.

Returns:

The content of the asset.

Return type:

bytes

Raises:
await save(fp, *, seek_begin=True)

This function is a coroutine.

Saves this asset into a file-like object.

Parameters:

  • fp (Union[io.BufferedIOBase, os.PathLike]) – The file-like object to save this attachment to or the filename to use. If a filename is passed then a file is created with that filename and used instead.

  • seek_begin (bool) – Whether to seek to the beginning of the file after saving is successfully done.

Returns:

The number of bytes written.

Return type:

int

Raises:
Attributes
class discord.components.MediaGalleryItem(url, *, description=None, spoiler=False)[source]

Represents an item used in the MediaGallery component.

Added in version 2.7.

Changed in version 3.0.

media

The UnfurledMediaItem associated with this media gallery item.

Type:

UnfurledMediaItem

description

The gallery item’s description, up to 1024 characters.

Type:

str | None

spoiler

Whether the gallery item is a spoiler.

Type:

bool

Parameters:

  • url (str) – The URL of this media gallery item. This can either be an arbitrary URL or an attachment:// URL to work with local files.

  • description (str | None) – The description of this media gallery item, up to 1024 characters. Defaults to None.

  • spoiler (bool) – Whether this media gallery item has a spoiler overlay. Defaults to False.

property url: str

Returns the URL of this gallery’s underlying media item.

Attributes
Methods
class discord.components.ComponentsHolder(*components: Unpack[Ts])[source]

A sequence of components that can be used in Discord Bot UI Kit.

This holder that is used to represent a collection of components, notably in a message.

Added in version 3.0.

get_by_id(component_id)[source]

Get a component by its custom ID.

Parameters:

component_id (str | int)

Return type:

ActionRow | Button | StringSelect | TextInput | UserSelect | RoleSelect | MentionableSelect | ChannelSelect | Section | TextDisplay | Thumbnail | MediaGallery | FileComponent | Separator | Container | Label | FileUpload | UnknownComponent | PartialLabel | PartialTextInput | PartialStringSelect | PartialTextDisplay | PartialUserSelect | PartialRoleSelect | PartialMentionableSelect | PartialChannelSelect | PartialFileUpload | UnknownPartialComponent | PartialButton | None

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

Attributes
Methods
class discord.components.DefaultSelectOption(id, type)[source]

Represents a default select menu option. Can only be used UserSelect, RoleSelect, and MentionableSelect.

Added in version 3.0.

id

The ID of the default option.

Type:

int

type

The type of the default option. This can be either “user”, “role”, or “channel”. This is used to determine which type of select menu this option belongs to.

Type:

str

Parameters:

  • id (int) – The ID of the default option.

  • type (TypeVar(DT, bound= Literal[“user”, “role”, “channel”])) – The type of the default option. This can be either “user”, “role”, or “channel”.

classmethod from_payload(payload)[source]

Creates a DefaultSelectOption from a dictionary.

Parameters:

payload (SelectDefaultValue[TypeVar(DT, bound= Literal[“user”, “role”, “channel”])])

Return type:

DefaultSelectOption[TypeVar(DT, bound= Literal[“user”, “role”, “channel”])]

to_dict()[source]

Converts the DefaultSelectOption to a dictionary.

Return type:

SelectDefaultValue[TypeVar(DT, bound= Literal[“user”, “role”, “channel”])]

ABCs

Attributes
Methods
class discord.components.Component(id=None)[source]

Represents a Discord Bot UI Kit Component.

This class is abstract and cannot be instantiated.

Added in version 2.0.

Changed in version 3.0.

type

The type of component.

Type:

ComponentType

id

The component’s ID.

Type:

int

Parameters:

id (int | None) – The component’s ID. If not provided by the user, it is set sequentially by Discord. The ID 0 is treated as if no ID was provided.

is_v2()[source]

Whether this component was introduced in Components V2.

Return type:

bool

any_is_v2()[source]

Whether this component or any of its children were introduced in Components V2.

Return type:

bool

is_dispatchable()[source]

Wether this component can be interacted with and lead to a Interaction

Return type:

bool

any_is_dispatchable()[source]

Whether this component or any of its children can be interacted with and lead to a Interaction

Return type:

bool

class discord.components.PartialComponent(id, type)[source]

Base class for all partial components returned by Discord during an Interaction of type InteractionType.modal_submit.

Added in version 3.0.

Parameters:

  • id (int)

  • type (TypeVar(T, bound= ComponentType))