Bot UI Kit¶
This section documents everything related to the Discord Bot UI Kit - a group of helper functions and classes that aid in making component-based UIs.
Classes¶
View¶
- clsView.from_message
- defadd_item
- defclear_items
- asyncinteraction_check
- defis_dispatching
- defis_finished
- defis_persistent
- asyncon_error
- asyncon_timeout
- defremove_item
- defstop
- asyncwait
- class disnake.ui.View(*, timeout=180.0)[source]¶
Represents a UI view.
This object must be inherited to create a UI within Discord.
Alternatively, components can be handled with
disnake.ui.ActionRow
s and event listeners for a more low-level approach. Relevant events aredisnake.on_button_click()
,disnake.on_dropdown()
, and the more genericdisnake.on_message_interaction()
.New in version 2.0.
- Parameters:
timeout (Optional[
float
]) – Timeout in seconds from last interaction with the UI before no longer accepting input. IfNone
then there is no timeout.
- timeout¶
Timeout from last interaction with the UI before no longer accepting input. If
None
then there is no timeout.- Type:
Optional[
float
]
- classmethod from_message(message, /, *, timeout=180.0)[source]¶
Converts a message’s components into a
View
.The
Message.components
of a message are read-only and separate types from those in thedisnake.ui
namespace. In order to modify and edit message components they must be converted into aView
first.- Parameters:
message (
disnake.Message
) – The message with components to convert into a view.timeout (Optional[
float
]) – The timeout of the converted view.
- Returns:
The converted view. This always returns a
View
and not one of its subclasses.- Return type:
- add_item(item)[source]¶
Adds an item to the view.
This function returns the class instance to allow for fluent-style chaining.
- Parameters:
item (
Item
) – The item to add to the view.- Raises:
ValueError – Maximum number of children has been exceeded (25) or the row the item is trying to be added to is full.
- remove_item(item)[source]¶
Removes an item from the view.
This function returns the class instance to allow for fluent-style chaining.
- Parameters:
item (
Item
) – The item to remove from the view.
- clear_items()[source]¶
Removes all items from the view.
This function returns the class instance to allow for fluent-style chaining.
- await interaction_check(interaction)[source]¶
This function is a coroutine.
A callback that is called when an interaction happens within the view that checks whether the view should process item callbacks for the interaction.
This is useful to override if, for example, you want to ensure that the interaction author is a given user.
The default implementation of this returns
True
.Note
If an exception occurs within the body then the check is considered a failure and
on_error()
is called.- Parameters:
interaction (
MessageInteraction
) – The interaction that occurred.- Returns:
Whether the view children’s callbacks should be called.
- Return type:
- await on_timeout()[source]¶
This function is a coroutine.
A callback that is called when a view’s timeout elapses without being explicitly stopped.
- await on_error(error, item, interaction)[source]¶
This function is a coroutine.
A callback that is called when an item’s callback or
interaction_check()
fails with an error.The default implementation prints the traceback to stderr.
- Parameters:
error (
Exception
) – The exception that was raised.item (
Item
) – The item that failed the dispatch.interaction (
MessageInteraction
) – The interaction that led to the failure.
- stop()[source]¶
Stops listening to interaction events from this view.
This operation cannot be undone.
ActionRow¶
- clsActionRow.rows_from_message
- clsActionRow.with_message_components
- clsActionRow.with_modal_components
- defadd_button
- defadd_channel_select
- defadd_mentionable_select
- defadd_role_select
- defadd_string_select
- defadd_text_input
- defadd_user_select
- defappend_item
- defclear_items
- definsert_item
- defpop
- defremove_item
- class disnake.ui.ActionRow(*components)[source]¶
Represents a UI action row. Useful for lower level component manipulation.
- x[i]
Returns the component at position
i
. Also supports slices.New in version 2.6.
- len(x)
Returns the number of components in this row.
New in version 2.6.
- iter(x)
Returns an iterator for the components in this row.
New in version 2.6.
To handle interactions created by components sent in action rows or entirely independently, event listeners must be used. For buttons and selects, the related events are
disnake.on_button_click()
anddisnake.on_dropdown()
, respectively. Alternatively,disnake.on_message_interaction()
can be used for either. For modals, the related event isdisnake.on_modal_submit()
.New in version 2.4.
Changed in version 2.6: Requires and provides stricter typing for contained components.
- Parameters:
*components (
WrappedComponent
) –The components of this action row.
Changed in version 2.6: Components can now be either valid in the context of a message, or in the context of a modal. Combining components from both contexts is not supported.
- property children[source]¶
Sequence[
WrappedComponent
]: A read-only copy of the UI components stored in this action row. To add/remove components to/from the action row, use its methods to directly modify it.Changed in version 2.6: Returns an immutable sequence instead of a list.
- append_item(item)[source]¶
Append a component to the action row. The component’s type must match that of the action row.
This function returns the class instance to allow for fluent-style chaining.
- Parameters:
item (
WrappedComponent
) – The component to append to the action row.- Raises:
ValueError – The width of the action row exceeds 5.
- insert_item(index, item)[source]¶
Insert a component to the action row at a given index. The component’s type must match that of the action row.
This function returns the class instance to allow for fluent-style chaining.
New in version 2.6.
- Parameters:
index (
int
) – The index at which to insert the component into the action row.item (
WrappedComponent
) – The component to insert into the action row.
- Raises:
ValueError – The width of the action row exceeds 5.
- add_button(index=None, *, style=ButtonStyle.secondary, label=None, disabled=False, custom_id=None, url=None, emoji=None, sku_id=None)[source]¶
Add a button to the action row. Can only be used if the action row holds message components.
To append a pre-existing
Button
use theappend_item()
method instead.This function returns the class instance to allow for fluent-style chaining.
Changed in version 2.6: Now allows for inserting at a given index. The default behaviour of appending is preserved.
- Parameters:
index (
int
) – The index at which to insert the button into the action row. If not provided, this method defaults to appending the button to the action row.style (
ButtonStyle
) – The style of the button.custom_id (Optional[
str
]) – 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.url (Optional[
str
]) – The URL this button sends you to.disabled (
bool
) – Whether the button is disabled or not.label (Optional[
str
]) – The label of the button, if any.emoji (Optional[Union[
PartialEmoji
,Emoji
,str
]]) – The emoji of the button, if available.sku_id (Optional[
int
]) –The ID of a purchasable SKU, for premium buttons. Premium buttons additionally cannot have a
label
,url
, oremoji
.New in version 2.11.
- Raises:
ValueError – The width of the action row exceeds 5.
- add_string_select(*, custom_id=..., placeholder=None, min_values=1, max_values=1, options=..., disabled=False)[source]¶
Add a string select menu to the action row. Can only be used if the action row holds message components.
To append a pre-existing
StringSelect
use theappend_item()
method instead.This function returns the class instance to allow for fluent-style chaining.
Changed in version 2.7: Renamed from
add_select
toadd_string_select
.- Parameters:
custom_id (
str
) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is selected, if any.min_values (
int
) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.max_values (
int
) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.options (Union[List[
disnake.SelectOption
], List[str
], Dict[str
,str
]]) – A list of options that can be selected in this menu. Use explicitSelectOption
s for fine-grained control over the options. Alternatively, a list of strings will be treated as a list of labels, and a dict will be treated as a mapping of labels to values.disabled (
bool
) – Whether the select is disabled or not.
- Raises:
ValueError – The width of the action row exceeds 5.
- add_user_select(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None)[source]¶
Add a user select menu to the action row. Can only be used if the action row holds message components.
To append a pre-existing
UserSelect
use theappend_item()
method instead.This function returns the class instance to allow for fluent-style chaining.
New in version 2.7.
- Parameters:
custom_id (
str
) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is selected, if any.min_values (
int
) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.max_values (
int
) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.disabled (
bool
) – Whether the select is disabled. Defaults toFalse
.default_values (Optional[Sequence[Union[
User
,Member
,SelectDefaultValue
,Object
]]]) –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
andmax_values
.New in version 2.10.
- Raises:
ValueError – The width of the action row exceeds 5.
- add_role_select(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None)[source]¶
Add a role select menu to the action row. Can only be used if the action row holds message components.
To append a pre-existing
RoleSelect
use theappend_item()
method instead.This function returns the class instance to allow for fluent-style chaining.
New in version 2.7.
- Parameters:
custom_id (
str
) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is selected, if any.min_values (
int
) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.max_values (
int
) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.disabled (
bool
) – Whether the select is disabled. Defaults toFalse
.default_values (Optional[Sequence[Union[
Role
,SelectDefaultValue
,Object
]]]) –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
andmax_values
.New in version 2.10.
- Raises:
ValueError – The width of the action row exceeds 5.
- add_mentionable_select(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None)[source]¶
Add a mentionable (user/member/role) select menu to the action row. Can only be used if the action row holds message components.
To append a pre-existing
MentionableSelect
use theappend_item()
method instead.This function returns the class instance to allow for fluent-style chaining.
New in version 2.7.
- Parameters:
custom_id (
str
) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is selected, if any.min_values (
int
) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.max_values (
int
) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.disabled (
bool
) – Whether the select is disabled. Defaults toFalse
.default_values (Optional[Sequence[Union[
User
,Member
,Role
,SelectDefaultValue
]]]) –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
andmax_values
.Note that unlike other select menu types, this does not support
Object
s due to ambiguities.New in version 2.10.
- Raises:
ValueError – The width of the action row exceeds 5.
- add_channel_select(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, channel_types=None, default_values=None)[source]¶
Add a channel select menu to the action row. Can only be used if the action row holds message components.
To append a pre-existing
ChannelSelect
use theappend_item()
method instead.This function returns the class instance to allow for fluent-style chaining.
New in version 2.7.
- Parameters:
custom_id (
str
) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is selected, if any.min_values (
int
) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.max_values (
int
) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.disabled (
bool
) – Whether the select is disabled. Defaults toFalse
.channel_types (Optional[List[
ChannelType
]]) – The list of channel types that can be selected in this select menu. Defaults to all types (i.e.None
).default_values (Optional[Sequence[Union[
abc.GuildChannel
,Thread
,abc.PrivateChannel
,PartialMessageable
,SelectDefaultValue
,Object
]]]) –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
andmax_values
.New in version 2.10.
- Raises:
ValueError – The width of the action row exceeds 5.
- add_text_input(*, label, custom_id, style=TextInputStyle.short, placeholder=None, value=None, required=True, min_length=None, max_length=None)[source]¶
Add a text input to the action row. Can only be used if the action row holds modal components.
To append a pre-existing
TextInput
use theappend_item()
method instead.This function returns the class instance to allow for fluent-style chaining.
New in version 2.4.
- Parameters:
style (
TextInputStyle
) – The style of the text input.label (
str
) – The label of the text input.custom_id (
str
) – The ID of the text input that gets received during an interaction.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is entered.value (Optional[
str
]) – The pre-filled value of the text input.required (
bool
) – Whether the text input is required. Defaults toTrue
.min_length (Optional[
int
]) – The minimum length of the text input.max_length (Optional[
int
]) – The maximum length of the text input.
- Raises:
ValueError – The width of the action row exceeds 5.
- clear_items()[source]¶
Remove all components from the action row.
This function returns the class instance to allow for fluent-style chaining.
New in version 2.6.
- remove_item(item)[source]¶
Remove a component from the action row.
This function returns the class instance to allow for fluent-style chaining.
New in version 2.6.
- Parameters:
item (
WrappedComponent
) – The component to remove from the action row.- Raises:
ValueError – The component could not be found on the action row.
- pop(index)[source]¶
Pop the component at the provided index from the action row.
New in version 2.6.
- Parameters:
index (
int
) – The index at which to pop the component.- Raises:
IndexError – There is no component at the provided index.
- classmethod with_modal_components()[source]¶
Create an empty action row meant to store components compatible with
disnake.ui.Modal
. Saves the need to import type specifiers to typehint empty action rows.New in version 2.6.
- Returns:
The newly created empty action row, intended for modal components.
- Return type:
- classmethod with_message_components()[source]¶
Create an empty action row meant to store components compatible with
disnake.Message
. Saves the need to import type specifiers to typehint empty action rows.New in version 2.6.
- Returns:
The newly created empty action row, intended for message components.
- Return type:
- classmethod rows_from_message(message, *, strict=True)[source]¶
Create a list of up to 5 action rows from the components on an existing message.
This will abide by existing component format on the message, including component ordering and rows. Components will be transformed to UI kit components, such that they can be easily modified and re-sent as action rows.
New in version 2.6.
- Parameters:
message (
disnake.Message
) – The message from which to extract the components.strict (
bool
) – Whether or not to raise an exception if an unknown component type is encountered.
- Raises:
TypeError – Strict-mode is enabled and an unknown component type is encountered.
- Returns:
The action rows parsed from the components on the message.
- Return type:
List[
ActionRow
]
- staticmethod for ... in walk_components(action_rows)[source]¶
Iterate over the components in a sequence of action rows, yielding each individual component together with the action row of which it is a child.
New in version 2.6.
- Parameters:
action_rows (Sequence[
ActionRow
]) – The sequence of action rows over which to iterate.- Yields:
Tuple[
ActionRow
,WrappedComponent
] – A tuple containing an action row and a component of that action row.
Item¶
- class disnake.ui.Item[source]¶
Represents the base UI item that all UI items inherit from.
This class adds more functionality on top of the
WrappedComponent
base class. This functionality mostly relates todisnake.ui.View
.The current UI items supported are:
subtypes of
disnake.ui.BaseSelect
(disnake.ui.ChannelSelect
,disnake.ui.MentionableSelect
,disnake.ui.RoleSelect
,disnake.ui.StringSelect
,disnake.ui.UserSelect
)
New in version 2.0.
- await callback(interaction, /)[source]¶
This function is a coroutine.
The callback associated with this UI item.
This can be overriden by subclasses.
- Parameters:
interaction (
MessageInteraction
) – The interaction that triggered this UI item.
WrappedComponent¶
- class disnake.ui.WrappedComponent[source]¶
Represents the base UI component that all UI components inherit from.
The following classes implement this ABC:
subtypes of
disnake.ui.BaseSelect
(disnake.ui.ChannelSelect
,disnake.ui.MentionableSelect
,disnake.ui.RoleSelect
,disnake.ui.StringSelect
,disnake.ui.UserSelect
)
New in version 2.4.
BaseSelect¶
- asynccallback
- defis_dispatchable
- class disnake.ui.BaseSelect(underlying_type, component_type, *, custom_id, placeholder, min_values, max_values, disabled, default_values, row)[source]¶
Represents an abstract UI select menu.
This is usually represented as a drop down menu.
This isn’t meant to be used directly, instead use one of the concrete select menu types:
New in version 2.7.
- property custom_id[source]¶
The ID of the select menu that gets received during an interaction.
- Type:
- property placeholder[source]¶
The placeholder text that is shown if nothing is selected, if any.
- Type:
Optional[
str
]
- property min_values[source]¶
The minimum number of items that must be chosen for this select menu.
- Type:
- property max_values[source]¶
The maximum number of items that must be chosen for this select menu.
- Type:
- property default_values[source]¶
The list of values that are selected by default. Only available for auto-populated select menus.
- Type:
List[
SelectDefaultValue
]
- await callback(interaction, /)[source]¶
This function is a coroutine.
The callback associated with this UI item.
This can be overriden by subclasses.
- Parameters:
interaction (
MessageInteraction
) – The interaction that triggered this UI item.
StringSelect¶
- defadd_option
- defappend_option
- asynccallback
- defis_dispatchable
- class disnake.ui.StringSelect(*, custom_id=..., placeholder=None, min_values=1, max_values=1, options=..., disabled=False, row=None)[source]¶
Represents a UI string select menu.
This is usually represented as a drop down menu.
In order to get the selected items that the user has chosen, use
values
.New in version 2.0.
Changed in version 2.7: Renamed from
Select
toStringSelect
.- Parameters:
custom_id (
str
) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is selected, if any.min_values (
int
) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.max_values (
int
) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.options (Union[List[
disnake.SelectOption
], List[str
], Dict[str
,str
]]) –A list of options that can be selected in this menu. Use explicit
SelectOption
s for fine-grained control over the options. Alternatively, a list of strings will be treated as a list of labels, and a dict will be treated as a mapping of labels to values.Changed in version 2.5: Now also accepts a list of str or a dict of str to str, which are then appropriately parsed as
SelectOption
labels and values.disabled (
bool
) – Whether the select is disabled.row (Optional[
int
]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults toNone
, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).
- property options[source]¶
A list of options that can be selected in this select menu.
- Type:
List[
disnake.SelectOption
]
- add_option(*, label, value=..., description=None, emoji=None, default=False)[source]¶
Adds an option to the select menu.
To append a pre-existing
SelectOption
use theappend_option()
method instead.- Parameters:
label (
str
) – The label of the option. This is displayed to users. Can only be up to 100 characters.value (
str
) – The value of the option. This is not displayed to users. If not given, defaults to the label. Can only be up to 100 characters.description (Optional[
str
]) – An additional description of the option, if any. Can only be up to 100 characters.emoji (Optional[Union[
str
,Emoji
,PartialEmoji
]]) – The emoji of the option, if available. This can either be a string representing the custom or unicode emoji or an instance ofPartialEmoji
orEmoji
.default (
bool
) – Whether this option is selected by default.
- Raises:
ValueError – The number of options exceeds 25.
- append_option(option)[source]¶
Appends an option to the select menu.
- Parameters:
option (
disnake.SelectOption
) – The option to append to the select menu.- Raises:
ValueError – The number of options exceeds 25.
- await callback(interaction, /)[source]¶
This function is a coroutine.
The callback associated with this UI item.
This can be overriden by subclasses.
- Parameters:
interaction (
MessageInteraction
) – The interaction that triggered this UI item.
- property custom_id[source]¶
The ID of the select menu that gets received during an interaction.
- Type:
- is_dispatchable()[source]¶
Whether the select menu is dispatchable. This will always return
True
.- Return type:
- property max_values[source]¶
The maximum number of items that must be chosen for this select menu.
- Type:
- property min_values[source]¶
The minimum number of items that must be chosen for this select menu.
- Type:
ChannelSelect¶
- asynccallback
- defis_dispatchable
- class disnake.ui.ChannelSelect(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, channel_types=None, default_values=None, row=None)[source]¶
Represents a UI channel select menu.
This is usually represented as a drop down menu.
In order to get the selected items that the user has chosen, use
values
.New in version 2.7.
- Parameters:
custom_id (
str
) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is selected, if any.min_values (
int
) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.max_values (
int
) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.disabled (
bool
) – Whether the select is disabled.channel_types (Optional[List[
ChannelType
]]) – The list of channel types that can be selected in this select menu. Defaults to all types (i.e.None
).default_values (Optional[Sequence[Union[
abc.GuildChannel
,Thread
,abc.PrivateChannel
,PartialMessageable
,SelectDefaultValue
,Object
]]]) –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
andmax_values
.New in version 2.10.
row (Optional[
int
]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults toNone
, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).
- values[source]¶
A list of channels that have been selected by the user.
- Type:
List[Union[
abc.GuildChannel
,Thread
,abc.PrivateChannel
,PartialMessageable
]]
- await callback(interaction, /)[source]¶
This function is a coroutine.
The callback associated with this UI item.
This can be overriden by subclasses.
- Parameters:
interaction (
MessageInteraction
) – The interaction that triggered this UI item.
- property channel_types[source]¶
A list of channel types that can be selected in this select menu.
- Type:
Optional[List[
disnake.ChannelType
]]
- property custom_id[source]¶
The ID of the select menu that gets received during an interaction.
- Type:
- property default_values[source]¶
The list of values that are selected by default. Only available for auto-populated select menus.
- Type:
List[
SelectDefaultValue
]
- is_dispatchable()[source]¶
Whether the select menu is dispatchable. This will always return
True
.- Return type:
- property max_values[source]¶
The maximum number of items that must be chosen for this select menu.
- Type:
- property min_values[source]¶
The minimum number of items that must be chosen for this select menu.
- Type:
MentionableSelect¶
- asynccallback
- defis_dispatchable
- class disnake.ui.MentionableSelect(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None, row=None)[source]¶
Represents a UI mentionable (user/member/role) select menu.
This is usually represented as a drop down menu.
In order to get the selected items that the user has chosen, use
values
.New in version 2.7.
- Parameters:
custom_id (
str
) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is selected, if any.min_values (
int
) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.max_values (
int
) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.disabled (
bool
) – Whether the select is disabled.default_values (Optional[Sequence[Union[
User
,Member
,Role
,SelectDefaultValue
]]]) –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
andmax_values
.Note that unlike other select menu types, this does not support
Object
s due to ambiguities.New in version 2.10.
row (Optional[
int
]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults toNone
, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).
- await callback(interaction, /)[source]¶
This function is a coroutine.
The callback associated with this UI item.
This can be overriden by subclasses.
- Parameters:
interaction (
MessageInteraction
) – The interaction that triggered this UI item.
- property custom_id[source]¶
The ID of the select menu that gets received during an interaction.
- Type:
- property default_values[source]¶
The list of values that are selected by default. Only available for auto-populated select menus.
- Type:
List[
SelectDefaultValue
]
- is_dispatchable()[source]¶
Whether the select menu is dispatchable. This will always return
True
.- Return type:
- property max_values[source]¶
The maximum number of items that must be chosen for this select menu.
- Type:
- property min_values[source]¶
The minimum number of items that must be chosen for this select menu.
- Type:
RoleSelect¶
- asynccallback
- defis_dispatchable
- class disnake.ui.RoleSelect(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None, row=None)[source]¶
Represents a UI role select menu.
This is usually represented as a drop down menu.
In order to get the selected items that the user has chosen, use
values
.New in version 2.7.
- Parameters:
custom_id (
str
) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is selected, if any.min_values (
int
) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.max_values (
int
) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.disabled (
bool
) – Whether the select is disabled.default_values (Optional[Sequence[Union[
Role
,SelectDefaultValue
,Object
]]]) –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
andmax_values
.New in version 2.10.
row (Optional[
int
]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults toNone
, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).
- await callback(interaction, /)[source]¶
This function is a coroutine.
The callback associated with this UI item.
This can be overriden by subclasses.
- Parameters:
interaction (
MessageInteraction
) – The interaction that triggered this UI item.
- property custom_id[source]¶
The ID of the select menu that gets received during an interaction.
- Type:
- property default_values[source]¶
The list of values that are selected by default. Only available for auto-populated select menus.
- Type:
List[
SelectDefaultValue
]
- is_dispatchable()[source]¶
Whether the select menu is dispatchable. This will always return
True
.- Return type:
- property max_values[source]¶
The maximum number of items that must be chosen for this select menu.
- Type:
- property min_values[source]¶
The minimum number of items that must be chosen for this select menu.
- Type:
UserSelect¶
- asynccallback
- defis_dispatchable
- class disnake.ui.UserSelect(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None, row=None)[source]¶
Represents a UI user select menu.
This is usually represented as a drop down menu.
In order to get the selected items that the user has chosen, use
values
.New in version 2.7.
- Parameters:
custom_id (
str
) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is selected, if any.min_values (
int
) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.max_values (
int
) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.disabled (
bool
) – Whether the select is disabled.default_values (Optional[Sequence[Union[
User
,Member
,SelectDefaultValue
,Object
]]]) –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
andmax_values
.New in version 2.10.
row (Optional[
int
]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults toNone
, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).
- await callback(interaction, /)[source]¶
This function is a coroutine.
The callback associated with this UI item.
This can be overriden by subclasses.
- Parameters:
interaction (
MessageInteraction
) – The interaction that triggered this UI item.
- property custom_id[source]¶
The ID of the select menu that gets received during an interaction.
- Type:
- property default_values[source]¶
The list of values that are selected by default. Only available for auto-populated select menus.
- Type:
List[
SelectDefaultValue
]
- is_dispatchable()[source]¶
Whether the select menu is dispatchable. This will always return
True
.- Return type:
- property max_values[source]¶
The maximum number of items that must be chosen for this select menu.
- Type:
- property min_values[source]¶
The minimum number of items that must be chosen for this select menu.
- Type:
Modal¶
- defadd_text_input
- defappend_component
- asynccallback
- asyncon_error
- asyncon_timeout
- class disnake.ui.Modal(*, title, components, custom_id=..., timeout=600)[source]¶
Represents a UI Modal.
New in version 2.4.
- Parameters:
title (
str
) – The title of the modal.components (Union[
disnake.ui.ActionRow
,disnake.ui.WrappedComponent
, List[Union[disnake.ui.ActionRow
,disnake.ui.WrappedComponent
, List[disnake.ui.WrappedComponent
]]]]) – The components to display in the modal. Up to 5 action rows.custom_id (
str
) –The custom ID of the modal. This is usually not required. If not given, then a unique one is generated for you.
Note
Modal
s are identified based on the user ID that triggered the modal, and thiscustom_id
. This can result in collisions when a user opens a modal with the samecustom_id
on two separate devices, for example.To avoid such issues, consider not specifying a
custom_id
to use an automatically generated one, or include a unique value in the custom ID (e.g. the original interaction ID).timeout (
float
) – The time to wait until the modal is removed from cache, if no interaction is made. Modals without timeouts are not supported, since there’s no event for when a modal is closed. Defaults to 600 seconds.
- append_component(component)[source]¶
Adds one or multiple component(s) to the modal.
- Parameters:
component (Union[
TextInput
, List[TextInput
]]) – The component(s) to add to the modal. This can be a single component or a list of components.- Raises:
ValueError – Maximum number of components (5) exceeded.
- add_text_input(*, label, custom_id, style=TextInputStyle.short, placeholder=None, value=None, required=True, min_length=None, max_length=None)[source]¶
Creates and adds a text input component to the modal.
To append a pre-existing instance of
TextInput
use theappend_component()
method.- Parameters:
label (
str
) – The label of the text input.custom_id (
str
) – The ID of the text input that gets received during an interaction.style (
TextInputStyle
) – The style of the text input.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is entered.value (Optional[
str
]) – The pre-filled value of the text input.required (
bool
) – Whether the text input is required. Defaults toTrue
.min_length (Optional[
int
]) – The minimum length of the text input.max_length (Optional[
int
]) – The maximum length of the text input.
- Raises:
ValueError – Maximum number of components (5) exceeded.
- await callback(interaction, /)[source]¶
This function is a coroutine.
The callback associated with this modal.
This can be overriden by subclasses.
- Parameters:
interaction (
ModalInteraction
) – The interaction that triggered this modal.
- await on_error(error, interaction)[source]¶
This function is a coroutine.
A callback that is called when an error occurs.
The default implementation prints the traceback to stderr.
- Parameters:
error (
Exception
) – The exception that was raised.interaction (
ModalInteraction
) – The interaction that triggered this modal.
TextInput¶
- class disnake.ui.TextInput(*, label, custom_id, style=TextInputStyle.short, placeholder=None, value=None, required=True, min_length=None, max_length=None)[source]¶
Represents a UI text input.
This can only be used in a
Modal
.New in version 2.4.
- Parameters:
label (
str
) – The label of the text input.custom_id (
str
) – The ID of the text input that gets received during an interaction.style (
TextInputStyle
) – The style of the text input.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is entered.value (Optional[
str
]) – The pre-filled value of the text input.required (
bool
) – Whether the text input is required. Defaults toTrue
.min_length (Optional[
int
]) – The minimum length of the text input.max_length (Optional[
int
]) – The maximum length of the text input.
- property custom_id[source]¶
The ID of the text input that gets received during an interaction.
- Type:
Functions¶
- @disnake.ui.button(cls=Button, *, custom_id=..., style=ButtonStyle.secondary, label=None, disabled=False, url=None, emoji=None, row=None)[source]¶
A decorator that attaches a button to a component.
The function being decorated should have three parameters,
self
representing thedisnake.ui.View
, thedisnake.ui.Button
that was interacted with, and thedisnake.MessageInteraction
.Note
Link/Premium buttons cannot be created with this function, since these buttons do not have a callback associated with them. Consider creating a
Button
manually instead, and adding it usingView.add_item()
.- Parameters:
cls (Callable[…,
Button
]) –A callable (may be a
Button
subclass) to create a new instance of this component. If provided, the other parameters described below do not apply. Instead, this decorator will accept the same keywords as the passed callable/class does.New in version 2.6.
label (Optional[
str
]) – The label of the button, if any.custom_id (Optional[
str
]) – The ID of the button that gets received during an interaction. It is recommended not to set this parameter to prevent conflicts.style (
ButtonStyle
) – The style of the button. Defaults toButtonStyle.grey
.disabled (
bool
) – Whether the button is disabled. Defaults toFalse
.emoji (Optional[Union[
str
,Emoji
,PartialEmoji
]]) – The emoji of the button. This can be in string form or aPartialEmoji
or a fullEmoji
.row (Optional[
int
]) – The relative row this button belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults toNone
, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).
- @disnake.ui.string_select(cls=StringSelect, *, custom_id=..., placeholder=None, min_values=1, max_values=1, options=..., disabled=False, row=None)[source]¶
A decorator that attaches a string select menu to a component.
The function being decorated should have three parameters,
self
representing thedisnake.ui.View
, thedisnake.ui.StringSelect
that was interacted with, and thedisnake.MessageInteraction
.In order to get the selected items that the user has chosen within the callback use
StringSelect.values
.Changed in version 2.7: Renamed from
select
tostring_select
.- Parameters:
cls (Callable[…,
StringSelect
]) –A callable (may be a
StringSelect
subclass) to create a new instance of this component. If provided, the other parameters described below do not apply. Instead, this decorator will accept the same keywords as the passed callable/class does.New in version 2.6.
placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is selected, if any.custom_id (
str
) – The ID of the select menu that gets received during an interaction. It is recommended not to set this parameter to prevent conflicts.row (Optional[
int
]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults toNone
, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).min_values (
int
) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.max_values (
int
) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.options (Union[List[
disnake.SelectOption
], List[str
], Dict[str
,str
]]) –A list of options that can be selected in this menu. Use explicit
SelectOption
s for fine-grained control over the options. Alternatively, a list of strings will be treated as a list of labels, and a dict will be treated as a mapping of labels to values.Changed in version 2.5: Now also accepts a list of str or a dict of str to str, which are then appropriately parsed as
SelectOption
labels and values.disabled (
bool
) – Whether the select is disabled. Defaults toFalse
.
- @disnake.ui.channel_select(cls=ChannelSelect, *, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, channel_types=None, default_values=None, row=None)[source]¶
A decorator that attaches a channel select menu to a component.
The function being decorated should have three parameters,
self
representing thedisnake.ui.View
, thedisnake.ui.ChannelSelect
that was interacted with, and thedisnake.MessageInteraction
.In order to get the selected items that the user has chosen within the callback use
ChannelSelect.values
.New in version 2.7.
- Parameters:
cls (Callable[…,
ChannelSelect
]) – A callable (may be aChannelSelect
subclass) to create a new instance of this component. If provided, the other parameters described below do not apply. Instead, this decorator will accept the same keywords as the passed callable/class does.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is selected, if any.custom_id (
str
) – The ID of the select menu that gets received during an interaction. It is recommended not to set this parameter to prevent conflicts.row (Optional[
int
]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults toNone
, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).min_values (
int
) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.max_values (
int
) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.disabled (
bool
) – Whether the select is disabled. Defaults toFalse
.channel_types (Optional[List[
ChannelType
]]) – The list of channel types that can be selected in this select menu. Defaults to all types (i.e.None
).default_values (Optional[Sequence[Union[
abc.GuildChannel
,Thread
,abc.PrivateChannel
,PartialMessageable
,SelectDefaultValue
,Object
]]]) –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
andmax_values
.New in version 2.10.
- @disnake.ui.mentionable_select(cls=MentionableSelect, *, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None, row=None)[source]¶
A decorator that attaches a mentionable (user/member/role) select menu to a component.
The function being decorated should have three parameters,
self
representing thedisnake.ui.View
, thedisnake.ui.MentionableSelect
that was interacted with, and thedisnake.MessageInteraction
.In order to get the selected items that the user has chosen within the callback use
MentionableSelect.values
.New in version 2.7.
- Parameters:
cls (Callable[…,
MentionableSelect
]) – A callable (may be aMentionableSelect
subclass) to create a new instance of this component. If provided, the other parameters described below do not apply. Instead, this decorator will accept the same keywords as the passed callable/class does.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is selected, if any.custom_id (
str
) – The ID of the select menu that gets received during an interaction. It is recommended not to set this parameter to prevent conflicts.row (Optional[
int
]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults toNone
, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).min_values (
int
) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.max_values (
int
) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.disabled (
bool
) – Whether the select is disabled. Defaults toFalse
.default_values (Optional[Sequence[Union[
User
,Member
,Role
,SelectDefaultValue
]]]) –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
andmax_values
.Note that unlike other select menu types, this does not support
Object
s due to ambiguities.New in version 2.10.
- @disnake.ui.role_select(cls=RoleSelect, *, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None, row=None)[source]¶
A decorator that attaches a role select menu to a component.
The function being decorated should have three parameters,
self
representing thedisnake.ui.View
, thedisnake.ui.RoleSelect
that was interacted with, and thedisnake.MessageInteraction
.In order to get the selected items that the user has chosen within the callback use
RoleSelect.values
.New in version 2.7.
- Parameters:
cls (Callable[…,
RoleSelect
]) – A callable (may be aRoleSelect
subclass) to create a new instance of this component. If provided, the other parameters described below do not apply. Instead, this decorator will accept the same keywords as the passed callable/class does.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is selected, if any.custom_id (
str
) – The ID of the select menu that gets received during an interaction. It is recommended not to set this parameter to prevent conflicts.row (Optional[
int
]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults toNone
, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).min_values (
int
) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.max_values (
int
) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.disabled (
bool
) – Whether the select is disabled. Defaults toFalse
.default_values (Optional[Sequence[Union[
Role
,SelectDefaultValue
,Object
]]]) –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
andmax_values
.New in version 2.10.
- @disnake.ui.user_select(cls=UserSelect, *, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None, row=None)[source]¶
A decorator that attaches a user select menu to a component.
The function being decorated should have three parameters,
self
representing thedisnake.ui.View
, thedisnake.ui.UserSelect
that was interacted with, and thedisnake.MessageInteraction
.In order to get the selected items that the user has chosen within the callback use
UserSelect.values
.New in version 2.7.
- Parameters:
cls (Callable[…,
UserSelect
]) – A callable (may be aUserSelect
subclass) to create a new instance of this component. If provided, the other parameters described below do not apply. Instead, this decorator will accept the same keywords as the passed callable/class does.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is selected, if any.custom_id (
str
) – The ID of the select menu that gets received during an interaction. It is recommended not to set this parameter to prevent conflicts.row (Optional[
int
]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults toNone
, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).min_values (
int
) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.max_values (
int
) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.disabled (
bool
) – Whether the select is disabled. Defaults toFalse
.default_values (Optional[Sequence[Union[
User
,Member
,SelectDefaultValue
,Object
]]]) –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
andmax_values
.New in version 2.10.