Components¶

This section documents everything related to message components — a Discord feature which allows bot developers to create their own component-based UIs right inside Discord.

Warning

Classes listed below are not meant to be created by user and are only received from the API. For constructible versions, see Bot UI Kit.

Discord Models¶

Component¶

Attributes

id
type

class disnake.Component[source]¶

Represents the base component that all other components inherit from.

The components supported by Discord are:

This class is abstract and cannot be instantiated.

Added in version 2.0.

type¶

The type of component.

Type:: ComponentType

id¶

The numeric identifier for the component. Must be unique within a message or modal. This is always present in components received from the API. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message or modal.

Added in version 2.11.

Type:: int

ActionRow¶

Attributes

children
id

class disnake.ActionRow[source]¶

Represents an 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.

children¶

The children components that this holds, if any.

Type:: list[Button | BaseSelectMenu | TextInput]

id¶

The numeric identifier for the component. Must be unique within a message. This is always present in components received from the API. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

Added in version 2.11.

Type:: int

Button¶

Attributes

custom_id
disabled
emoji
id
label
sku_id
style
url

class disnake.Button[source]¶

Represents a button from the Discord Bot UI Kit.

This inherits from Component.

Note

The user constructible and usable type to create a button is disnake.ui.Button, not this one.

Added in version 2.0.

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 or an SKU, 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 a purchasable SKU, for premium buttons. Premium buttons additionally cannot have a label, url, or emoji.

Added in version 2.11.

Type:: int | None

id¶

Added in version 2.11.

Type:: int

BaseSelectMenu¶

Attributes

custom_id
default_values
disabled
id
max_values
min_values
options
placeholder
required

class disnake.BaseSelectMenu[source]¶

Represents an abstract select menu from the Discord Bot UI Kit.

A select menu is functionally the same as a dropdown, however on mobile it renders a bit differently.

The currently supported select menus are:

StringSelectMenu
UserSelectMenu
RoleSelectMenu
MentionableSelectMenu
ChannelSelectMenu

Added in version 2.7.

custom_id¶

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

Type:: str | None

placeholder¶

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

Type:: str | None

min_values¶

The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

Type:: int

max_values¶

The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

Type:: int

options¶

A list of options that can be selected in this select menu.

Type:: list[SelectOption]

disabled¶

Whether the select menu is disabled or not.

Type:: bool

default_values¶

The list of values (users/roles/channels) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values. Only available for auto-populated select menus.

Added in version 2.10.

Type:: list[SelectDefaultValue]

required¶

Whether the select menu is required. Only applies to components in modals. Defaults to True.

Added in version 2.11.

Type:: bool

id¶

Added in version 2.11.

Type:: int

ChannelSelectMenu¶

Attributes

channel_types
custom_id
default_values
disabled
id
max_values
min_values
placeholder
required

class disnake.ChannelSelectMenu[source]¶

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

Note

The user constructible and usable type to create a channel select menu is disnake.ui.ChannelSelect.

Added in version 2.7.

custom_id¶

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

Type:: str | None

placeholder¶

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

Type:: str | None

min_values¶

The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

Type:: int

max_values¶

The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

Type:: int

disabled¶

Whether the select menu is disabled or not.

Type:: bool

channel_types¶

A list of channel types that can be selected in this select menu. If None, channels of all types may be selected.

Type:: list[ChannelType] | None

default_values¶

The list of values (channels) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values.

Added in version 2.10.

Type:: list[SelectDefaultValue]

required¶

Whether the select menu is required. Only applies to components in modals. Defaults to True.

Added in version 2.11.

Type:: bool

id¶

Added in version 2.11.

Type:: int

MentionableSelectMenu¶

Attributes

custom_id
default_values
disabled
id
max_values
min_values
placeholder
required

class disnake.MentionableSelectMenu[source]¶

Represents a mentionable (user/member/role) select menu from the Discord Bot UI Kit.

Note

The user constructible and usable type to create a mentionable select menu is disnake.ui.MentionableSelect.

Added in version 2.7.

custom_id¶

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

Type:: str | None

placeholder¶

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

Type:: str | None

min_values¶

The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

Type:: int

max_values¶

The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

Type:: int

disabled¶

Whether the select menu is disabled or not.

Type:: bool

default_values¶

The list of values (users/roles) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values.

Added in version 2.10.

Type:: list[SelectDefaultValue]

required¶

Whether the select menu is required. Only applies to components in modals. Defaults to True.

Added in version 2.11.

Type:: bool

id¶

Added in version 2.11.

Type:: int

RoleSelectMenu¶

Attributes

custom_id
default_values
disabled
id
max_values
min_values
placeholder
required

class disnake.RoleSelectMenu[source]¶

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

Note

The user constructible and usable type to create a role select menu is disnake.ui.RoleSelect.

Added in version 2.7.

custom_id¶

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

Type:: str | None

placeholder¶

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

Type:: str | None

min_values¶

The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

Type:: int

max_values¶

The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

Type:: int

disabled¶

Whether the select menu is disabled or not.

Type:: bool

default_values¶

The list of values (roles) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values.

Added in version 2.10.

Type:: list[SelectDefaultValue]

required¶

Whether the select menu is required. Only applies to components in modals. Defaults to True.

Added in version 2.11.

Type:: bool

id¶

Added in version 2.11.

Type:: int

StringSelectMenu¶

Attributes

custom_id
disabled
id
max_values
min_values
options
placeholder
required

class disnake.StringSelectMenu[source]¶

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

Note

The user constructible and usable type to create a string select menu is disnake.ui.StringSelect.

Added in version 2.0.

Changed in version 2.7: Renamed from SelectMenu to StringSelectMenu.

custom_id¶

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

Type:: str | None

placeholder¶

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

Type:: str | None

min_values¶

The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

Type:: int

max_values¶

The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

Type:: int

disabled¶

Whether the select menu is disabled or not.

Type:: bool

options¶

A list of options that can be selected in this select menu.

Type:: list[SelectOption]

required¶

Whether the select menu is required. Only applies to components in modals. Defaults to True.

Added in version 2.11.

Type:: bool

id¶

Added in version 2.11.

Type:: int

UserSelectMenu¶

Attributes

custom_id
default_values
disabled
id
max_values
min_values
placeholder
required

class disnake.UserSelectMenu[source]¶

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

Note

The user constructible and usable type to create a user select menu is disnake.ui.UserSelect.

Added in version 2.7.

custom_id¶

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

Type:: str | None

placeholder¶

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

Type:: str | None

min_values¶

The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

Type:: int

max_values¶

The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

Type:: int

disabled¶

Whether the select menu is disabled or not.

Type:: bool

default_values¶

The list of values (users/members) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values.

Added in version 2.10.

Type:: list[SelectDefaultValue]

required¶

Whether the select menu is required. Only applies to components in modals. Defaults to True.

Added in version 2.11.

Type:: bool

id¶

Added in version 2.11.

Type:: int

SelectOption¶

Attributes

default
description
emoji
label
value

class disnake.SelectOption(*, label, value=..., description=None, emoji=None, default=False)[source]¶

Represents a string select menu’s option.

These can be created by users.

Added in version 2.0.

label¶

The label of the option. This is displayed to users. Can only be up to 100 characters.

Type:: str

value¶

The value of the option. This is not displayed to users. If not provided when constructed then it defaults to the label. Can only be up to 100 characters.

Type:: str

description¶

An additional description of the option, if any. Can only be up to 100 characters.

Type:: str | None

emoji¶

The emoji of the option, if available.

Type:: str | Emoji | PartialEmoji | None

default¶

Whether this option is selected by default.

Type:: bool

SelectDefaultValue¶

Attributes

id
type

class disnake.SelectDefaultValue(id, type)[source]¶

Represents a default value of an auto-populated select menu (currently all select menu types except StringSelectMenu).

Depending on the type attribute, this can represent different types of objects.

Added in version 2.10.

id¶

The ID of the target object.

Type:: int

type¶

The type of the target object.

Type:: SelectDefaultValueType

TextInput¶

Attributes

custom_id
id
label
max_length
min_length
placeholder
required
style
value

class disnake.TextInput[source]¶

Represents a text input from the Discord Bot UI Kit.

Added in version 2.4.

Note

The user constructible and usable type to create a text input is disnake.ui.TextInput, not this one.

style¶

The style of the text input.

Type:: TextInputStyle

label¶

The label of the text input.

Deprecated since version 2.11: Deprecated in favor of Label.

Type:: str | None

custom_id¶

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

Type:: str

placeholder¶

The placeholder text that is shown if nothing is entered.

Type:: str | None

value¶

The pre-filled text of the text input.

Type:: str | None

required¶

Whether the text input is required. Defaults to True.

Type:: bool

min_length¶

The minimum length of the text input.

Type:: int | None

max_length¶

The maximum length of the text input.

Type:: int | None

id¶

The numeric identifier for the component. Must be unique within a modal. This is always present in components received from the API. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the modal.

Added in version 2.11.

Type:: int

Section¶

Attributes

accessory
children
id

class disnake.Section[source]¶

Represents a section from the Discord Bot UI Kit (v2).

This allows displaying an accessory (thumbnail or button) next to a block of text.

Note

The user constructible and usable type to create a section is disnake.ui.Section.

Added in version 2.11.

children¶

The text items in this section.

Type:: list[TextDisplay]

accessory¶

The accessory component displayed next to the section text.

Type:: Thumbnail | Button

id¶

Added in version 2.11.

Type:: int

TextDisplay¶

Attributes

content
id

class disnake.TextDisplay[source]¶

Represents a text display from the Discord Bot UI Kit (v2).

Note

The user constructible and usable type to create a text display is disnake.ui.TextDisplay.

Added in version 2.11.

content¶

The text displayed by this component.

Type:: str

id¶

Added in version 2.11.

Type:: int

UnfurledMediaItem¶

Attributes

attachment_id
content_type
height
proxy_url
url
width

class disnake.UnfurledMediaItem[source]¶

Represents an unfurled/resolved media item within a component.

Added in version 2.11.

url¶

The URL of this media item.

Type:: str

proxy_url¶

The proxied URL of this media item. This is a cached version of the url in the case of images.

Type:: str

height¶

The height of this media item, if applicable.

Type:: int | None

width¶

The width of this media item, if applicable.

Type:: int | None

content_type¶

The media type of this media item.

Type:: str | None

attachment_id¶

The ID of the uploaded attachment. Only present if the media item was uploaded as an attachment.

Type:: int | None

Thumbnail¶

Attributes

description
id
media
spoiler

class disnake.Thumbnail[source]¶

Represents a thumbnail from the Discord Bot UI Kit (v2).

This is only supported as the accessory of a section component.

Note

The user constructible and usable type to create a thumbnail is disnake.ui.Thumbnail.

Added in version 2.11.

media¶

The media item to display. Can be an arbitrary URL or attachment reference (attachment://<filename>).

Type:: UnfurledMediaItem

description¶

The thumbnail’s description (“alt text”), if any.

Type:: str | None

spoiler¶

Whether the thumbnail is marked as a spoiler. Defaults to False.

Type:: bool

id¶

Added in version 2.11.

Type:: int

MediaGallery¶

Attributes

id
items

class disnake.MediaGallery[source]¶

Represents a media gallery from the Discord Bot UI Kit (v2).

This allows displaying up to 10 images in a gallery.

Note

The user constructible and usable type to create a media gallery is disnake.ui.MediaGallery.

Added in version 2.11.

items¶

The images in this gallery.

Type:: list[MediaGalleryItem]

id¶

Added in version 2.11.

Type:: int

MediaGalleryItem¶

class disnake.MediaGalleryItem(media, description=None, *, spoiler=False)[source]¶

Represents an item inside a MediaGallery.

Added in version 2.11.

Parameters:

media (str | Asset | Attachment | UnfurledMediaItem) – The media item to display. Can be an arbitrary URL or attachment reference (attachment://<filename>).
description (str | None) – The item’s description (“alt text”), if any.
spoiler (bool) – Whether the item is marked as a spoiler. Defaults to False.

FileComponent¶

Attributes

file
id
name
size
spoiler

class disnake.FileComponent[source]¶

Represents a file component from the Discord Bot UI Kit (v2).

This allows displaying attached files.

Note

The user constructible and usable type to create a file component is disnake.ui.File.

Added in version 2.11.

file¶

The file to display. This only supports attachment references (i.e. using the attachment://<filename> syntax), not arbitrary URLs.

Type:: UnfurledMediaItem

spoiler¶

Whether the file is marked as a spoiler. Defaults to False.

Type:: bool

name¶

The name of the file. This is available in objects from the API, and ignored when sending.

Type:: str | None

size¶

The size of the file. This is available in objects from the API, and ignored when sending.

Type:: int | None

id¶

Added in version 2.11.

Type:: int

Separator¶

Attributes

divider
id
spacing

class disnake.Separator[source]¶

Represents a separator from the Discord Bot UI Kit (v2).

This allows vertically separating components.

Note

The user constructible and usable type to create a separator is disnake.ui.Separator.

Added in version 2.11.

divider¶

Whether the separator should be visible, instead of just being vertical padding/spacing. Defaults to True.

Type:: bool

spacing¶

The size of the separator padding.

Type:: SeparatorSpacing

id¶

Added in version 2.11.

Type:: int

Container¶

Attributes

accent_color
accent_colour
children
id
spoiler

class disnake.Container[source]¶

Represents a container from the Discord Bot UI Kit (v2).

This is visually similar to Embeds, and contains other components.

Note

The user constructible and usable type to create a container is disnake.ui.Container.

Added in version 2.11.

children¶

The child components in this container.

Type:: list[ActionRow | Section | TextDisplay | MediaGallery | FileComponent | Separator]

accent_colour¶

The accent colour of the container. An alias exists under accent_color.

Type:: Colour | None

spoiler¶

Whether the container is marked as a spoiler. Defaults to False.

Type:: bool

id¶

Added in version 2.11.

Type:: int

property accent_color[source]¶

The accent color of the container. An alias exists under accent_colour.

Type:: Colour | None

Label¶

Attributes

component
description
id
text

class disnake.Label[source]¶

Represents a label from the Discord Bot UI Kit.

This wraps other components with a label and an optional description, and can only be used in modals.

Added in version 2.11.

Note

The user constructible and usable type to create a label is disnake.ui.Label, not this one.

text¶

The label text.

Type:: str

description¶

The description text for the label.

Type:: str | None

component¶

The component within the label.

Type:: TextInput | FileUpload | BaseSelectMenu | RadioGroup | CheckboxGroup | Checkbox

id¶

Type:: int

FileUpload¶

Attributes

custom_id
id
max_values
min_values
required

class disnake.FileUpload[source]¶

Represents a file upload component from the Discord Bot UI Kit.

This allows you to receive files from users, and can only be used in modals.

Note

The user constructible and usable type to create a file upload is disnake.ui.FileUpload.

Added in version 2.12.

custom_id¶

The ID of the file upload that gets received during an interaction.

Type:: str

min_values¶

The minimum number of files that must be uploaded. Defaults to 1 and must be between 0 and 10.

Type:: int

max_values¶

The maximum number of files that must be uploaded. Defaults to 1 and must be between 1 and 10.

Type:: int

required¶

Whether the file upload is required. Defaults to True.

Type:: bool

id¶

Type:: int

GroupOption¶

class disnake.GroupOption[source]¶

Represents an option inside a RadioGroup or CheckboxGroup.

Added in version 2.12.

Parameters:

label (str) – The label of the option. This is displayed to users. Can be up to 100 characters.
value (str) – The value of the option. This is not displayed to users. If not provided when constructed then it defaults to the label. Can be up to 100 characters.
description (str | None) – The options’s description, if any.
default (bool) – Whether this option is selected by default. Defaults to False.

RadioGroup¶

Attributes

custom_id
id
options
required

class disnake.RadioGroup[source]¶

Represents a component containing radio buttons/options from the Discord Bot UI Kit.

This requires users to select exactly one out of the given options, and can only be used in modals.

Note

The user constructible and usable type to create a radio group is disnake.ui.RadioGroup.

Added in version 2.12.

custom_id¶

The ID of the radio group that gets received during an interaction.

Type:: str

options¶

A list of options that can be selected in this group (2-10).

Type:: list[GroupOption]

required¶

Whether selecting an option in this radio group is required. Defaults to True.

Type:: bool

id¶

Type:: int

CheckboxGroup¶

Attributes

custom_id
id
max_values
min_values
options
required

class disnake.CheckboxGroup[source]¶

Represents a component containing checkboxes from the Discord Bot UI Kit.

This requires users to select up to 10 checkboxes, and can only be used in modals. For single checkboxes, see Checkbox.

Note

The user constructible and usable type to create a checkbox group is disnake.ui.CheckboxGroup.

Added in version 2.12.

custom_id¶

The ID of the checkbox group that gets received during an interaction.

Type:: str

options¶

A list of options that can be selected in this group (1-10).

Type:: list[GroupOption]

min_values¶

The minimum number of options that must be selected in this group. Defaults to 1 and must be between 0 and 10.

Type:: int

max_values¶

The maximum number of options that must be selected in this group. Must be between 1 and 10. If set to None (the default), all options can be selected.

Type:: int | None

required¶

Whether selecting an option in this checkbox group is required. Defaults to True.

Type:: bool

id¶

Type:: int

Checkbox¶

Attributes

custom_id
default
id

class disnake.Checkbox[source]¶

Represents a single checkbox component from the Discord Bot UI Kit.

This can only be used in modals. For a group of multiple checkboxes, see CheckboxGroup.

Note

The user constructible and usable type to create a checkbox is disnake.ui.Checkbox.

Added in version 2.12.

custom_id¶

The ID of the checkbox that gets received during an interaction.

Type:: str

default¶

Whether this checkbox is selected by default. Defaults to False.

Type:: bool

id¶

Type:: int

Enumerations¶

ComponentType¶

class disnake.ComponentType[source]¶

Represents the type of component.

Added in version 2.0.

action_row¶: Represents the group component which holds different components in a row.

button¶: Represents a button component.

string_select¶: Represents a string select component.

Added in version 2.7.

select¶: An alias of string_select.

text_input¶: Represents a text input component.

user_select¶: Represents a user select component.

Added in version 2.7.

role_select¶: Represents a role select component.

Added in version 2.7.

mentionable_select¶: Represents a mentionable (user/member/role) select component.

Added in version 2.7.

channel_select¶: Represents a channel select component.

Added in version 2.7.

section¶: Represents a Components V2 section component.

Added in version 2.11.

text_display¶: Represents a Components V2 text display component.

Added in version 2.11.

thumbnail¶: Represents a Components V2 thumbnail component.

Added in version 2.11.

media_gallery¶: Represents a Components V2 media gallery component.

Added in version 2.11.

file¶: Represents a Components V2 file component.

Added in version 2.11.

separator¶: Represents a Components V2 separator component.

Added in version 2.11.

container¶: Represents a Components V2 container component.

Added in version 2.11.

label¶: Represents a label component.

Added in version 2.11.

file_upload¶: Represents a file upload component.

Added in version 2.12.

radio_group¶: Represents a radio group component.

Added in version 2.12.

checkbox_group¶: Represents a checkbox group component.

Added in version 2.12.

checkbox¶: Represents a checkbox component.

Added in version 2.12.

ButtonStyle¶

class disnake.ButtonStyle[source]¶

Represents the style of the button component.

Added in version 2.0.

primary¶: Represents a blurple button for the primary action.

secondary¶: Represents a grey button for the secondary action.

success¶: Represents a green button for a successful action.

danger¶: Represents a red button for a dangerous action.

link¶: Represents a link button.

premium¶: Represents a premium/SKU button.

Added in version 2.11.

blurple¶: An alias for primary.

grey¶: An alias for secondary.

gray¶: An alias for secondary.

green¶: An alias for success.

red¶: An alias for danger.

url¶: An alias for link.

sku¶: An alias for premium.

Added in version 2.11.

TextInputStyle¶

class disnake.TextInputStyle[source]¶

Represents a style of the text input component.

Added in version 2.4.

short¶: Represents a single-line text input component.

paragraph¶: Represents a multi-line text input component.

single_line¶: An alias for short.

multi_line¶: An alias for paragraph.

long¶: An alias for paragraph.

SelectDefaultValueType¶

class disnake.SelectDefaultValueType[source]¶

Represents the type of a SelectDefaultValue.

Added in version 2.10.

user¶: Represents a user/member.

role¶: Represents a role.

channel¶: Represents a channel.

SeparatorSpacing¶

class disnake.SeparatorSpacing[source]¶

Specifies the size of a Separator component’s padding.

Added in version 2.11.

small¶: Small spacing.

large¶: Large spacing.