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
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. This is always present in components received from the API, and unique within a message. 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

ActionRow

Attributes
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[Union[Button, BaseSelectMenu, TextInput]]

id

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

Added in version 2.11.

Type:

int

Button

Attributes
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:

Optional[str]

url

The URL this button sends you to.

Type:

Optional[str]

disabled

Whether the button is disabled or not.

Type:

bool

label

The label of the button, if any.

Type:

Optional[str]

emoji

The emoji of the button, if available.

Type:

Optional[PartialEmoji]

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:

Optional[int]

id

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

Added in version 2.11.

Type:

int

BaseSelectMenu

Attributes
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:

Added in version 2.7.

custom_id

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

Type:

Optional[str]

placeholder

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

Type:

Optional[str]

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

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

Added in version 2.11.

Type:

int

ChannelSelectMenu

Attributes
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:

Optional[str]

placeholder

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

Type:

Optional[str]

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:

Optional[List[ChannelType]]

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

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

Added in version 2.11.

Type:

int

MentionableSelectMenu

Attributes
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:

Optional[str]

placeholder

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

Type:

Optional[str]

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

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

Added in version 2.11.

Type:

int

RoleSelectMenu

Attributes
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:

Optional[str]

placeholder

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

Type:

Optional[str]

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

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

Added in version 2.11.

Type:

int

StringSelectMenu

Attributes
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:

Optional[str]

placeholder

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

Type:

Optional[str]

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

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

Added in version 2.11.

Type:

int

UserSelectMenu

Attributes
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:

Optional[str]

placeholder

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

Type:

Optional[str]

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

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

Added in version 2.11.

Type:

int

SelectOption

Attributes
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:

Optional[str]

emoji

The emoji of the option, if available.

Type:

Optional[Union[str, Emoji, PartialEmoji]]

default

Whether this option is selected by default.

Type:

bool

SelectDefaultValue

Attributes
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
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:

Optional[str]

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:

Optional[str]

value

The pre-filled text of the text input.

Type:

Optional[str]

required

Whether the text input is required. Defaults to True.

Type:

bool

min_length

The minimum length of the text input.

Type:

Optional[int]

max_length

The maximum length of the text input.

Type:

Optional[int]

id

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

Added in version 2.11.

Type:

int

Section

Attributes
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:

Union[Thumbnail, Button]

id

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

Added in version 2.11.

Type:

int

TextDisplay

Attributes
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

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

Added in version 2.11.

Type:

int

UnfurledMediaItem

Attributes
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:

Optional[int]

width

The width of this media item, if applicable.

Type:

Optional[int]

content_type

The media type of this media item.

Type:

Optional[str]

attachment_id

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

Type:

Optional[int]

Thumbnail

Attributes
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:

Optional[str]

spoiler

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

Type:

bool

id

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

Added in version 2.11.

Type:

int

MediaGallery

Attributes
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

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

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 (Union[str, Asset, Attachment, UnfurledMediaItem]) – The media item to display. Can be an arbitrary URL or attachment reference (attachment://<filename>).

  • description (Optional[str]) – The item’s description (“alt text”), if any.

  • spoiler (bool) – Whether the item is marked as a spoiler. Defaults to False.

FileComponent

Attributes
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:

Optional[str]

size

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

Type:

Optional[int]

id

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

Added in version 2.11.

Type:

int

Separator

Attributes
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

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

Added in version 2.11.

Type:

int

Container

Attributes
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[Union[ActionRow, Section, TextDisplay, MediaGallery, FileComponent, Separator]]

accent_colour

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

Type:

Optional[Colour]

spoiler

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

Type:

bool

id

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

Added in version 2.11.

Type:

int

property accent_color[source]

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

Type:

Optional[Colour]

Label

Attributes
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:

Optional[str]

component

The component within the label.

Type:

Union[TextInput, StringSelectMenu]

id

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

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.

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.

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.

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.