ActionRow

Attributes
Methods
class discord.ActionRow

Bases: Generic[T]

Represents an ActionRow-Part for the components of a Message or Modal.

components

The components the ActionRow holds. This could be up to five Button, one Select like object or one TextInput.

Type:

List[Union[Button, Select, TextInput]]

Represents an ActionRow-Part for the components of a Message.

Parameters:

*components (Union[Button, Select, TextInput]) – This could be up to five Button, one Select like object or one TextInput.

add_component(component)

Adds a component to the ActionRow and returns itself.

Parameters:

component (Union[Button, Select, TextInput]) – The component to add to the ActionRow.

Returns:

The updated instance

Return type:

ActionRow

insert_component_at(index, component)

Inserts a component before a specified index to the ActionRow and returns itself.

Parameters:

  • index (int) – The index of where to insert the component.

  • component (Union[Button, Select, TextInput]) – The component to insert.

Returns:

The updated instance

Return type:

ActionRow

set_component_at(index, component)

Modifies a component to the ActionRow and returns itself.

Note

The index must point to a valid pre-existing component.

Parameters:

  • index (int) – The index of the component to modify.

  • component (Union[Button, Select, TextInput]) – The component to replace the old one with.

Raises:

IndexError – An invalid index was provided.

Returns:

The updated instance

Return type:

ActionRow

disable_component_at(index)

Disables the component at the specified position of the ActionRow and returns itself.

Parameters:

index (int) – The position of the component to be deactivated in the ActionRow.

Raises:

IndexError – The specified index is outside the length of the actionRow.

Returns:

The updated instance

Return type:

ActionRow

add_components(*components)

Adds multiple components to the ActionRow and returns itself.

Parameters:

*components (Union[Button, Select, TextInput]) – The components to add to the Action Row.

Returns:

The updated instance

Return type:

ActionRow

disable_all_components()

Disables all components in this ActionRow and returns itself.

Returns:

The updated instance

Return type:

ActionRow

disable_all_components_if(check, *args, **kwargs)

Disables all components in this ActionRow if the passed check returns True and returns itself.

Parameters:

  • check (Union[bool, Callable[[Any, …], bool ]]) – Could be an bool or usually any Callable that returns a bool

  • *args (Any) – Positional arguments that should be passed in to the check if it is a Callable

  • **kwargs (Any) – Keyword-only arguments that should be passed in to the check if it is a Callable

Returns:

The updated instance

Return type:

ActionRow

disable_all_buttons()

Disables any Button in this ActionRow and returns itself.

Returns:

The updated instance

Return type:

ActionRow

disable_all_buttons_if(check, *args, **kwargs)

Disables any Button in this ActionRow if the passed check returns True and returns itself.

Parameters:

  • check (Union[bool, Callable[[Any, …], bool ]]) – Could be an bool or usually any Callable that returns a bool

  • *args (Any) – Positional arguments that should be passed in to the check if it is a Callable

  • **kwargs (Any) – Keyword-only arguments that should be passed in to the check if it is a Callable

Returns:

The updated instance

Return type:

ActionRow

disable_all_select_menus()

Disables all Select like objects in this ActionRow and returns itself.

Returns:

The updated instance

Return type:

ActionRow

disable_all_select_menus_if(check, *args, **kwargs)

Disables all Select like objects in this ActionRow if the passed check returns True and returns itself.

Parameters:

  • check (Union[bool, Callable[[Any, …], bool ]]) – Could be an bool or usually any Callable that returns a bool

  • *args (Any) – Positional arguments that should be passed in to the check if it is a Callable

  • **kwargs (Any) – Keyword-only arguments that should be passed in to the check if it is a Callable

Returns:

The updated instance

Return type:

ActionRow

classmethod from_dict(data)

Internal method to create a ActionRow from the data given by discord.

Parameters:

data (dict) – The raw data from the api.

Returns:

The ActionRow created.

Return type:

ActionRow

Button

Attributes
Methods
class discord.Button

Bases: BaseComponent

Represents a :ddocs:`Discord-Button <interactions/message-components#button-object>`_

Represents a :ddocs:`Discord-Button <interactions/message-components#button-object>`_ component.

Parameters:

  • label (Optional[str]:) – Text that appears on the button, max 80 characters

  • custom_id (Optional[Union[str, int]) – See BaseComponent.custom_id

  • style (Optional[Union[ButtonStyle, int]]) – The ButtonStyle the button should have, defaults to grey

  • emoji (Optional[Union[PartialEmoji, Emoji, str]]:) – An emoji that will be displayed on the left side of the button.

  • url (Optional[str]) – An URL for the button if it is of type ButtonStyle.url

  • sku_id (Optional[int]) – The purchasable SKU’s identifier when using ButtonStyle.Premium. Note that a premium button can only have this attribute as well as Button.disabled set and can not have a custom_id, label, url or emoji.

property type

The type this component is of

Type:

ComponentType

property style

The ButtonStyle the button should have, defaults to grey

Type:

Optional[Union[ButtonStyle, int]]

property label

Text that appears on the button, max 80 characters

Type:

Optional[str]

property emoji

An emoji that will be displayed on the left side of the button.

Type:

Optional[Union[PartialEmoji, Emoji, str]]

property url

An URL for the button if it is of type ButtonStyle.url

Type:

Optional[str]

property sku_id

The purchasable SKU’s identifier when style is set to ButtonStyle.Premium

Type:

Optional[int]

set_label(label)

Sets the Label of the Button

label: str

The label to replace th old one with.

Returns:

The updated instance

Return type:

Button

set_url(url)

Sets the url of the Button

url: Optional[str]

The url to replace the old one with

Returns:

The updated instance

Return type:

Button

set_custom_id(custom_id)

Sets the custom_id of the Button

custom_id: Union[str, int]

The custom_id to replace the old one with

Returns:

The updated instance

Return type:

Button

disable_if(check, *args, **kwargs)

Disables the Button if the passed check returns True and return itself.

Parameters:

  • check (Union[bool, Callable[[Any, …], bool ]]) – Could be an bool or usually any Callable that returns a bool

  • *args (Any) – Positional arguments that should be passed in to the check if it is a Callable

  • **kwargs (Any) – Keyword-only arguments that should be passed in to the check if it is a Callable

Returns:

The updated instance

Return type:

Button

set_style_if(check, style, *args, **kwargs)

Sets the style of the Button to the specified one if the specified check returns True.

Parameters:

  • check (Union[bool, Callable[[Any, …], bool]]) – Could be an bool or usually any Callable that returns a bool

  • style (discord.ButtonStyle) – The style the Button should have when the check returns True

  • *args (Any) – Positional arguments that should be passed in to the check if it is a Callable

  • **kwargs (Any) – Keyword-only arguments that should be passed in to the check if it is a Callable

Returns:

The updated instance

Return type:

Button

property custom_id

Union[str, int] (depending on whether it is completely numeric or not):

A developer defined ID for this component. This must be unique per Message/Modal Max. 100 characters long.

Note

The custom ID is a good place to store any additional data. For example if you want to make a check in the callback whether the author is a specific user just store the user-id in the custom_id like

# The custom_id
custom_id=f'some-prefix:{ctx.author.id}'

# Now you can extract this information again in the callback by splitting it at the separator.
_, author_id = custom_id.split(':')  # Note that the author_id is still a string here, not an integer!

Of course, you can store any and as much data in it as you want. (As long as it does not exceed the max. length)

property disabled

Whether this component can be used or not. If True it is greyed out in the client.

Type:

bool

SelectMenu

Attributes
Methods
class discord.SelectMenu

Bases: BaseSelect

Represents a Select-Menu

Parameters:

  • custom_id (Union[str, int]) – A developer-defined identifier for the SelectMenu, max. 100 characters

  • options (List[SelectOption]) – A list of options to choose from, max. 25

  • placeholder (Optional[str]) – Custom placeholder text if nothing is selected, max. 100 characters

  • min_values (Optional[int]) – The minimum number of items that must be chosen; default 1, min. 0, max. 25

  • max_values (Optional[int]) – The maximum number of items that can be chosen; default 1, max. 25

  • disabled (Optional[bool]) – Disables the SelectMenu, default False

property type

The type this component is of

Type:

ComponentType

property options

A list of options to choose from, max. 25.

Note

This must include at least the amount of min_values/max_values

Type:

List[SelectOption]

all_option_values

All values of the options of the SelectMenu.

Warning

If the value is a number it is returned as an int, otherwise as str!

Note

This is equal to

for option in self.options:
    if option.value.isdigit():
        yield int(option.value)
    else:
        yield option.value
values

The values of the options that were selected

Note

This only exists if the SelectMenu is passed as an argument in an interaction.

Warning

If the value is a number it is returned as an int, otherwise as str!

Raises:

TypeError – The SelectMenu was not passed as an argument for an interaction-callback

Returns:

A list containing the values of the selected options

Return type:

List[Union[int, str]]

not_selected

The options that were not selected

Note

This only exists if the SelectMenu is passed as a parameter in an interaction.

Warning

If the value is a number it is returned as an int, otherwise as str!

Raises:

TypeError – The SelectMenu was not passed as an argument for an interaction-callback

Returns:

A list containing the values of all not selected options

Return type:

List[Union[int, str]]

property custom_id

Union[str, int] (depending on whether it is completely numeric or not):

A developer defined ID for this component. This must be unique per Message/Modal Max. 100 characters long.

Note

The custom ID is a good place to store any additional data. For example if you want to make a check in the callback whether the author is a specific user just store the user-id in the custom_id like

# The custom_id
custom_id=f'some-prefix:{ctx.author.id}'

# Now you can extract this information again in the callback by splitting it at the separator.
_, author_id = custom_id.split(':')  # Note that the author_id is still a string here, not an integer!

Of course, you can store any and as much data in it as you want. (As long as it does not exceed the max. length)

disable_if(check, *args, **kwargs)

Disables the Select if the passed check returns True and returns itself.

Parameters:

  • check (Union[bool, Callable[[Any, …], bool ]]) – Could be an bool or usually any Callable that returns a bool

  • *args (Any) – Positional arguments that should be passed in to the check if it is a Callable

  • **kwargs (Any) – Keyword-only arguments that should be passed in to the check if it is a Callable

Returns:

The updated instance

Return type:

Union[SelectMenu, UserSelect, RoleSelect, MentionableSelect, ChannelSelect]

property disabled

Whether this component can be used or not. If True it is greyed out in the client.

Type:

bool

property max_values

The maximum number of items that can be chosen; default 1, max. 25.

Type:

int

property min_values

The minimum number of items that must be chosen; default 1, min. 0, max. 25.

Type:

int

property placeholder

Custom placeholder text if nothing is selected, max. 100 characters.

Type:

Optional[str]

set_custom_id(custom_id)

Set the custom_id of the Select

Parameters:

custom_id (Union[str, int]) – The custom_id to replace the old one with

Returns:

The instance with the updated custom_id

Return type:

Union[SelectMenu, UserSelect, RoleSelect, MentionableSelect, ChannelSelect]

SelectOption

Attributes
class discord.SelectOption

Bases: object

A class that represents an option for a SelectMenu

label

the user-facing name of the option, max 25 characters

Type:

str

value

the dev-define value of the option, max 100 characters

Type:

str

description

an additional description of the option, max 50 characters

Type:

Optional[str] = None

emoji

an Emoji that will be shown on the left side of the option.

Type:

Union[PartialEmoji, Emoji, str] = None

default

will render this option as selected by default

Type:

Optional[bool] = False

Raises:

ValueError – One of label, value or description is too long.

SelectDefaultValue

class discord.SelectDefaultValue

Bases: object

A default value for a UserSelect, RoleSelect, MentionableSelect or ChannelSelect

Note

As all of those select types except MentionableSelect accept only one type of value, you can for those just use instances of the mentioned type or a int/str/discord.Object and the library will convert them to default values for you. However, this might be slower than just providing instances of this class.

Parameters:

  • id (Union[int, str, discord.Object]) – The ID of a user, role, or channel

  • type (Optional[SelectDefaultValueType]) – The type of the value that id represents. If not passed, it will be tried to be inferred from the type of id. (Must be not an int/str then)

UserSelect

Attributes
Methods
class discord.UserSelect

Bases: BaseSelect

Very similar to SelectMenu but you can select from a list of Member/User

Note

options can’t be set for this type. But you can set default_values to a list of Member/User to set the default values.

See also

SelectDefaultValue

property default_values

A list of values to select by default, must be within the range of min_values and max_values

Type:

List[SelectDefaultValue]

property type

The type this component is of

Type:

ComponentType

values

The members/users that were selected

Note

This only exists if the UserSelect is passed as a parameter in an interaction.

Returns:

A list of selected members or user if the member is not found

Return type:

List[Union[Member, User]]

property custom_id

Union[str, int] (depending on whether it is completely numeric or not):

A developer defined ID for this component. This must be unique per Message/Modal Max. 100 characters long.

Note

The custom ID is a good place to store any additional data. For example if you want to make a check in the callback whether the author is a specific user just store the user-id in the custom_id like

# The custom_id
custom_id=f'some-prefix:{ctx.author.id}'

# Now you can extract this information again in the callback by splitting it at the separator.
_, author_id = custom_id.split(':')  # Note that the author_id is still a string here, not an integer!

Of course, you can store any and as much data in it as you want. (As long as it does not exceed the max. length)

disable_if(check, *args, **kwargs)

Disables the Select if the passed check returns True and returns itself.

Parameters:

  • check (Union[bool, Callable[[Any, …], bool ]]) – Could be an bool or usually any Callable that returns a bool

  • *args (Any) – Positional arguments that should be passed in to the check if it is a Callable

  • **kwargs (Any) – Keyword-only arguments that should be passed in to the check if it is a Callable

Returns:

The updated instance

Return type:

Union[SelectMenu, UserSelect, RoleSelect, MentionableSelect, ChannelSelect]

property disabled

Whether this component can be used or not. If True it is greyed out in the client.

Type:

bool

property max_values

The maximum number of items that can be chosen; default 1, max. 25.

Type:

int

property min_values

The minimum number of items that must be chosen; default 1, min. 0, max. 25.

Type:

int

property placeholder

Custom placeholder text if nothing is selected, max. 100 characters.

Type:

Optional[str]

set_custom_id(custom_id)

Set the custom_id of the Select

Parameters:

custom_id (Union[str, int]) – The custom_id to replace the old one with

Returns:

The instance with the updated custom_id

Return type:

Union[SelectMenu, UserSelect, RoleSelect, MentionableSelect, ChannelSelect]

RoleSelect

Attributes
Methods
class discord.RoleSelect

Bases: BaseSelect

Very similar to SelectMenu but you can select from a list of Role

Note

options can’t be set for this type. But you can set default_values to a list of Role to set the default values.

See also

SelectDefaultValue

property default_values

A list of roles to select by default, must be within the range of min_values and max_values

Type:

List[SelectDefaultValue]

property type

The type this component is of

Type:

ComponentType

values

The roles that were selected

Note

This only exists if the RoleSelect is passed as a parameter in an interaction.

Returns:

A list of selected roles

Return type:

List[Role]

property custom_id

Union[str, int] (depending on whether it is completely numeric or not):

A developer defined ID for this component. This must be unique per Message/Modal Max. 100 characters long.

Note

The custom ID is a good place to store any additional data. For example if you want to make a check in the callback whether the author is a specific user just store the user-id in the custom_id like

# The custom_id
custom_id=f'some-prefix:{ctx.author.id}'

# Now you can extract this information again in the callback by splitting it at the separator.
_, author_id = custom_id.split(':')  # Note that the author_id is still a string here, not an integer!

Of course, you can store any and as much data in it as you want. (As long as it does not exceed the max. length)

disable_if(check, *args, **kwargs)

Disables the Select if the passed check returns True and returns itself.

Parameters:

  • check (Union[bool, Callable[[Any, …], bool ]]) – Could be an bool or usually any Callable that returns a bool

  • *args (Any) – Positional arguments that should be passed in to the check if it is a Callable

  • **kwargs (Any) – Keyword-only arguments that should be passed in to the check if it is a Callable

Returns:

The updated instance

Return type:

Union[SelectMenu, UserSelect, RoleSelect, MentionableSelect, ChannelSelect]

property disabled

Whether this component can be used or not. If True it is greyed out in the client.

Type:

bool

property max_values

The maximum number of items that can be chosen; default 1, max. 25.

Type:

int

property min_values

The minimum number of items that must be chosen; default 1, min. 0, max. 25.

Type:

int

property placeholder

Custom placeholder text if nothing is selected, max. 100 characters.

Type:

Optional[str]

set_custom_id(custom_id)

Set the custom_id of the Select

Parameters:

custom_id (Union[str, int]) – The custom_id to replace the old one with

Returns:

The instance with the updated custom_id

Return type:

Union[SelectMenu, UserSelect, RoleSelect, MentionableSelect, ChannelSelect]

MentionableSelect

Attributes
Methods
class discord.MentionableSelect

Bases: BaseSelect

Very similar to SelectMenu but you can select from a list of both Member/User and Role

Note

options can’t be set for this type. But you can set default_values to a list of Member/User/Role to set the default values.

See also

SelectDefaultValue

property default_values

A list of values to select by default, must be within the range of min_values and max_values

Type:

List[SelectDefaultValue]

property type

The type this component is of

Type:

ComponentType

values

The members/users and roles that were selected

Note

This only exists if the MentionableSelect is passed as a parameter in an interaction.

Returns:

A list of selected members/users and roles

Return type:

List[Union[Member, User, Role]]

property custom_id

Union[str, int] (depending on whether it is completely numeric or not):

A developer defined ID for this component. This must be unique per Message/Modal Max. 100 characters long.

Note

The custom ID is a good place to store any additional data. For example if you want to make a check in the callback whether the author is a specific user just store the user-id in the custom_id like

# The custom_id
custom_id=f'some-prefix:{ctx.author.id}'

# Now you can extract this information again in the callback by splitting it at the separator.
_, author_id = custom_id.split(':')  # Note that the author_id is still a string here, not an integer!

Of course, you can store any and as much data in it as you want. (As long as it does not exceed the max. length)

disable_if(check, *args, **kwargs)

Disables the Select if the passed check returns True and returns itself.

Parameters:

  • check (Union[bool, Callable[[Any, …], bool ]]) – Could be an bool or usually any Callable that returns a bool

  • *args (Any) – Positional arguments that should be passed in to the check if it is a Callable

  • **kwargs (Any) – Keyword-only arguments that should be passed in to the check if it is a Callable

Returns:

The updated instance

Return type:

Union[SelectMenu, UserSelect, RoleSelect, MentionableSelect, ChannelSelect]

property disabled

Whether this component can be used or not. If True it is greyed out in the client.

Type:

bool

property max_values

The maximum number of items that can be chosen; default 1, max. 25.

Type:

int

property min_values

The minimum number of items that must be chosen; default 1, min. 0, max. 25.

Type:

int

property placeholder

Custom placeholder text if nothing is selected, max. 100 characters.

Type:

Optional[str]

set_custom_id(custom_id)

Set the custom_id of the Select

Parameters:

custom_id (Union[str, int]) – The custom_id to replace the old one with

Returns:

The instance with the updated custom_id

Return type:

Union[SelectMenu, UserSelect, RoleSelect, MentionableSelect, ChannelSelect]

ChannelSelect

Attributes
Methods
class discord.ChannelSelect

Bases: BaseSelect

Very similar to SelectMenu but you can select from a list of channels.

For this type there is an additional parameter channel_types which can be a list of ChannelType (or the type itself like TextChannel or StageChannel) that specify from what channel types the user could choose.

Note

options can’t be set for this type. But you can set default_values to a list of channels to set as the default values.

See also

SelectDefaultValue

property custom_id

Union[str, int] (depending on whether it is completely numeric or not):

A developer defined ID for this component. This must be unique per Message/Modal Max. 100 characters long.

Note

The custom ID is a good place to store any additional data. For example if you want to make a check in the callback whether the author is a specific user just store the user-id in the custom_id like

# The custom_id
custom_id=f'some-prefix:{ctx.author.id}'

# Now you can extract this information again in the callback by splitting it at the separator.
_, author_id = custom_id.split(':')  # Note that the author_id is still a string here, not an integer!

Of course, you can store any and as much data in it as you want. (As long as it does not exceed the max. length)

disable_if(check, *args, **kwargs)

Disables the Select if the passed check returns True and returns itself.

Parameters:

  • check (Union[bool, Callable[[Any, …], bool ]]) – Could be an bool or usually any Callable that returns a bool

  • *args (Any) – Positional arguments that should be passed in to the check if it is a Callable

  • **kwargs (Any) – Keyword-only arguments that should be passed in to the check if it is a Callable

Returns:

The updated instance

Return type:

Union[SelectMenu, UserSelect, RoleSelect, MentionableSelect, ChannelSelect]

property disabled

Whether this component can be used or not. If True it is greyed out in the client.

Type:

bool

property max_values

The maximum number of items that can be chosen; default 1, max. 25.

Type:

int

property min_values

The minimum number of items that must be chosen; default 1, min. 0, max. 25.

Type:

int

property placeholder

Custom placeholder text if nothing is selected, max. 100 characters.

Type:

Optional[str]

set_custom_id(custom_id)

Set the custom_id of the Select

Parameters:

custom_id (Union[str, int]) – The custom_id to replace the old one with

Returns:

The instance with the updated custom_id

Return type:

Union[SelectMenu, UserSelect, RoleSelect, MentionableSelect, ChannelSelect]

property type

The type this component is of

Type:

ComponentType

property default_values

List[GuildChannel]: A list of channels to select by default, must be within the range of min_values and max_values

values

The channels that were selected

Note

This only exists if the ChannelSelect is passed as a parameter in an interaction.

Returns:

A list of selected channels

Return type:

List[Union[GuildChannel, Messageable]]

TextInput

Attributes
class discord.TextInput

Bases: BaseComponent

Represents a TextInput

Parameters:

  • custom_id (Optional[Union[str, int]]) – A developer-defined identifier for the input, max 100 characters

  • style (Optional[Union[TextInputStyle, int]] = TextInputStyle.short) – The Style of the TextInput; so single- or multi-line

  • label (str) – The label for this component, max 45 characters

  • min_length (Optional[int]) – The minimum input length for a text input, min 0, max 4000

  • max_length (Optional[int]) – The maximum input length for a text input, min 1, max 4000

  • required (Optional[bool] = True) – Whether this component is required to be filled, default True

  • value (Optional[str]) – A pre-filled value for this component, max 4000 characters

  • placeholder (Optional[str]) – Custom placeholder text if the input is empty, max 100 characters

property type

The type this component is of

Type:

ComponentType

property custom_id

Union[str, int] (depending on whether it is completely numeric or not):

A developer defined ID for this component. This must be unique per Message/Modal Max. 100 characters long.

Note

The custom ID is a good place to store any additional data. For example if you want to make a check in the callback whether the author is a specific user just store the user-id in the custom_id like

# The custom_id
custom_id=f'some-prefix:{ctx.author.id}'

# Now you can extract this information again in the callback by splitting it at the separator.
_, author_id = custom_id.split(':')  # Note that the author_id is still a string here, not an integer!

Of course, you can store any and as much data in it as you want. (As long as it does not exceed the max. length)

property disabled

Whether this component can be used or not. If True it is greyed out in the client.

Type:

bool