Bot UI Kit#
The library has helpers to help create component-based UIs.
Shortcut decorators#
- @discord.ui.button(*, label=None, custom_id=None, disabled=False, style=<ButtonStyle.secondary: 2>, emoji=None, row=None)[source]#
A decorator that attaches a button to a component.
The function being decorated should have three parameters,
self
representing thediscord.ui.View
, thediscord.ui.Button
being pressed and thediscord.Interaction
you receive.Note
Premium and link buttons cannot be created with this decorator. Consider creating a
Button
object manually instead. These types of buttons do not have a callback associated since Discord doesn’t handle them when clicked.- Parameters:
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 or not. 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).
- Return type:
Callable[[ItemCallbackType], ItemCallbackType]
- @discord.ui.select(select_type=<ComponentType.string_select: 3>, *, placeholder=None, custom_id=None, min_values=1, max_values=1, options=..., channel_types=..., disabled=False, row=None)[source]#
A decorator that attaches a select menu to a component.
The function being decorated should have three parameters,
self
representing thediscord.ui.View
, thediscord.ui.Select
being pressed and thediscord.Interaction
you receive.In order to get the selected items that the user has chosen within the callback use
Select.values
.Changed in version 2.3: Creating select menus of different types is now supported.
- Parameters:
select_type (
discord.ComponentType
) – The type of select to create. Must be one ofdiscord.ComponentType.string_select
,discord.ComponentType.user_select
,discord.ComponentType.role_select
,discord.ComponentType.mentionable_select
, ordiscord.ComponentType.channel_select
.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 0 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 (List[
discord.SelectOption
]) – A list of options that can be selected in this menu. Only valid for thediscord.ComponentType.string_select
type.channel_types (List[
discord.ChannelType
]) – The channel types that should be selectable. Only valid for thediscord.ComponentType.channel_select
type. Defaults to all channel types.disabled (
bool
) – Whether the select is disabled or not. Defaults toFalse
.
- Return type:
Callable[[ItemCallbackType], ItemCallbackType]
- @discord.ui.string_select(*, placeholder=None, custom_id=None, min_values=1, max_values=1, options=..., disabled=False, row=None)[source]#
A shortcut for
discord.ui.select()
with select typediscord.ComponentType.string_select
.New in version 2.3.
- @discord.ui.user_select(*, placeholder=None, custom_id=None, min_values=1, max_values=1, disabled=False, row=None)[source]#
A shortcut for
discord.ui.select()
with select typediscord.ComponentType.user_select
.New in version 2.3.
- @discord.ui.role_select(*, placeholder=None, custom_id=None, min_values=1, max_values=1, disabled=False, row=None)[source]#
A shortcut for
discord.ui.select()
with select typediscord.ComponentType.role_select
.New in version 2.3.
- @discord.ui.mentionable_select(*, placeholder=None, custom_id=None, min_values=1, max_values=1, disabled=False, row=None)[source]#
A shortcut for
discord.ui.select()
with select typediscord.ComponentType.mentionable_select
.New in version 2.3.
- @discord.ui.channel_select(*, placeholder=None, custom_id=None, min_values=1, max_values=1, disabled=False, channel_types=..., row=None)[source]#
A shortcut for
discord.ui.select()
with select typediscord.ComponentType.channel_select
.New in version 2.3.
Objects#
- clsView.from_message
- defadd_item
- defclear_items
- defdisable_all_items
- defenable_all_items
- defget_item
- asyncinteraction_check
- defis_dispatching
- defis_finished
- defis_persistent
- asyncon_check_failure
- asyncon_error
- asyncon_timeout
- defremove_item
- defstop
- asyncwait
- class discord.ui.View(*items, timeout=180.0, disable_on_timeout=False)[source]#
Represents a UI view.
This object must be inherited to create a UI within Discord.
New in version 2.0.
- Parameters:
- timeout#
Timeout from last interaction with the UI before no longer accepting input. If
None
then there is no timeout.- Type:
Optional[
float
]
- disable_on_timeout#
Whether to disable the view when the timeout is reached. Defaults to
False
.- Type:
- message#
The message that this view is attached to. If
None
then the view has not been sent with a message.- Type:
Optional[
Message
]
- parent#
The parent interaction which this view was sent from. If
None
then the view was not sent usingInteractionResponse.send_message()
.- Type:
Optional[
Interaction
]
- Parameters:
disable_on_timeout (bool) –
- 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 thediscord.ui
namespace. In order to modify and edit message components they must be converted into aView
first.
- add_item(item)[source]#
Adds an item to the view.
- 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.
- Return type:
- get_item(custom_id)[source]#
Get an item from the view with the given custom ID. Alias for utils.get(view.children, custom_id=custom_id).
- 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
.If this returns
False
,on_check_failure()
is called.Note
If an exception occurs within the body then the check is considered a failure and
on_error()
is called.- Parameters:
interaction (
Interaction
) – 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.
- Return type:
- await on_check_failure(interaction)[source]#
This function is a coroutine. A callback that is called when a
View.interaction_check()
returnsFalse
. This can be used to send a response when a check failure occurs.- Parameters:
interaction (
Interaction
) – The interaction that occurred.- Return type:
- 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 (
Interaction
) – The interaction that led to the failure.
- Return type:
- stop()[source]#
Stops listening to interaction events from this view.
This operation cannot be undone.
- Return type:
- is_persistent()[source]#
Whether the view is set up as persistent.
A persistent view has all their components with a set
custom_id
and atimeout
set toNone
.- Return type:
- await wait()[source]#
Waits until the view has finished interacting.
A view is considered finished when
stop()
is called, or it times out.- Returns:
If
True
, then the view timed out. IfFalse
then the view finished normally.- Return type:
- class discord.ui.Item[source]#
Represents the base UI item that all UI components inherit from.
The current UI items supported are:
New in version 2.0.
- property view#
The underlying view for this item.
- await callback(interaction)[source]#
This function is a coroutine.
The callback associated with this UI item.
This can be overridden by subclasses.
- Parameters:
interaction (
Interaction
) – The interaction that triggered this UI item.
- class discord.ui.Button(*, style=<ButtonStyle.secondary: 2>, label=None, disabled=False, custom_id=None, url=None, emoji=None, sku_id=None, row=None)[source]#
Represents a UI button.
New in version 2.0.
- Parameters:
style (
discord.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. Maximum of 80 chars.emoji (Optional[Union[
PartialEmoji
,Emoji
,str
]]) – The emoji of the button, if available.sku_id (Optional[Union[
int
]]) – The ID of the SKU this button refers to.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).
- property style#
The style of the button.
- property custom_id#
The ID of the button that gets received during an interaction.
If this button is for a URL, it does not have a custom ID.
- property url#
The URL this button sends you to.
- property disabled#
Whether the button is disabled or not.
- property label#
The label of the button, if available.
- property emoji#
The emoji of the button, if available.
- property sku_id#
The ID of the SKU this button refers to.
- await callback(interaction)#
This function is a coroutine.
The callback associated with this UI item.
This can be overridden by subclasses.
- Parameters:
interaction (
Interaction
) – The interaction that triggered this UI item.
- property view#
The underlying view for this item.
- defadd_option
- defappend_option
- asynccallback
- class discord.ui.Select(select_type=<ComponentType.string_select: 3>, *, custom_id=None, placeholder=None, min_values=1, max_values=1, options=None, channel_types=None, disabled=False, row=None)[source]#
Represents a UI select menu.
This is usually represented as a drop down menu.
In order to get the selected items that the user has chosen, use
Select.values
.New in version 2.0.
Changed in version 2.3: Added support for
discord.ComponentType.string_select
,discord.ComponentType.user_select
,discord.ComponentType.role_select
,discord.ComponentType.mentionable_select
, anddiscord.ComponentType.channel_select
.- Parameters:
select_type (
discord.ComponentType
) – The type of select to create. Must be one ofdiscord.ComponentType.string_select
,discord.ComponentType.user_select
,discord.ComponentType.role_select
,discord.ComponentType.mentionable_select
, ordiscord.ComponentType.channel_select
.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 (List[
discord.SelectOption
]) – A list of options that can be selected in this menu. Only valid for selects of typediscord.ComponentType.string_select
.channel_types (List[
discord.ChannelType
]) – A list of channel types that can be selected in this menu. Only valid for selects of typediscord.ComponentType.channel_select
.disabled (
bool
) – Whether the select is disabled or not.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 custom_id#
The ID of the select menu that gets received during an interaction.
- property placeholder#
The placeholder text that is shown if nothing is selected, if any.
- property min_values#
The minimum number of items that must be chosen for this select menu.
- property max_values#
The maximum number of items that must be chosen for this select menu.
- property disabled#
Whether the select is disabled or not.
- property channel_types#
A list of channel types that can be selected in this menu.
- property options#
A list of options that can be selected in this menu.
- add_option(*, label, value=..., description=None, emoji=None, default=False)[source]#
Adds an option to the select menu.
To append a pre-existing
discord.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 (
discord.SelectOption
) – The option to append to the select menu.- Raises:
ValueError – The number of options exceeds 25.
- property values#
List[
str
] | List[discord.Member
|discord.User
]] | List[discord.Role
]] | List[discord.Member
|discord.User
|discord.Role
]] | List[discord.abc.GuildChannel
] | None: A list of values that have been selected by the user. This will beNone
if the select has not been interacted with yet.
- await callback(interaction)#
This function is a coroutine.
The callback associated with this UI item.
This can be overridden by subclasses.
- Parameters:
interaction (
Interaction
) – The interaction that triggered this UI item.
- property view#
The underlying view for this item.
- defadd_item
- asynccallback
- asyncon_error
- asyncon_timeout
- defremove_item
- defstop
- asyncwait
- class discord.ui.Modal(*children, title, custom_id=None, timeout=None)[source]#
Represents a UI Modal dialog.
This object must be inherited to create a UI within Discord.
New in version 2.0.
- Parameters:
children (
InputText
) – The initial InputText fields that are displayed in the modal dialog.title (
str
) – The title of the modal dialog. Must be 45 characters or fewer.custom_id (Optional[
str
]) – The ID of the modal dialog that gets received during an interaction. Must be 100 characters or fewer.timeout (Optional[
float
]) – Timeout in seconds from last interaction with the UI before no longer accepting input. IfNone
then there is no timeout.
- property title#
The title of the modal dialog.
- property children#
The child components associated with the modal dialog.
- property custom_id#
The ID of the modal dialog that gets received during an interaction.
- await callback(interaction)[source]#
This function is a coroutine.
The coroutine that is called when the modal dialog is submitted. Should be overridden to handle the values submitted by the user.
- Parameters:
interaction (
Interaction
) – The interaction that submitted the modal dialog.
- add_item(item)[source]#
Adds an InputText component to the modal dialog.
- Parameters:
item (
InputText
) – The item to add to the modal dialog
- remove_item(item)[source]#
Removes an InputText component from the modal dialog.
- Parameters:
item (
InputText
) – The item to remove from the modal dialog.
- await on_error(error, interaction)[source]#
This function is a coroutine.
A callback that is called when the modal’s callback fails with an error.
The default implementation prints the traceback to stderr.
- Parameters:
error (
Exception
) – The exception that was raised.interaction (
Interaction
) – The interaction that led to the failure.
- Return type:
- class discord.ui.InputText(*, style=<InputTextStyle.short: 1>, custom_id=None, label, placeholder=None, min_length=None, max_length=None, required=True, value=None, row=None)[source]#
Represents a UI text input field.
New in version 2.0.
- Parameters:
style (
InputTextStyle
) – The style of the input text field.custom_id (Optional[
str
]) – The ID of the input text field that gets received during an interaction.label (
str
) – The label for the input text field. Must be 45 characters or fewer.placeholder (Optional[
str
]) – The placeholder text that is shown if nothing is selected, if any. Must be 100 characters or fewer.min_length (Optional[
int
]) – The minimum number of characters that must be entered. Defaults to 0 and must be less than 4000.max_length (Optional[
int
]) – The maximum number of characters that can be entered. Must be between 1 and 4000.required (Optional[
bool
]) – Whether the input text field is required or not. Defaults toTrue
.value (Optional[
str
]) – Pre-fills the input text field with this value. Must be 4000 characters or fewer.row (Optional[
int
]) – The relative row this input text field belongs to. A modal dialog 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 style#
The style of the input text field.
- property custom_id#
The ID of the input text field that gets received during an interaction.
- property label#
The label of the input text field.
- property placeholder#
The placeholder text that is shown before anything is entered, if any.
- property min_length#
The minimum number of characters that must be entered. Defaults to 0.
- property max_length#
The maximum number of characters that can be entered.
- property required#
Whether the input text field is required or not. Defaults to
True
.
- property value#
The value entered in the text field.