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 the discord.ui.View, the discord.ui.Button being pressed and the discord.Interaction you receive.

Note

Buttons with a URL cannot be created with this function. Consider creating a Button manually instead. This is because buttons with a URL do not have a callback associated with them since Discord does not do any processing with it.

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 to ButtonStyle.grey.

  • disabled (bool) – Whether the button is disabled or not. Defaults to False.

  • emoji (Optional[Union[str, Emoji, PartialEmoji]]) – The emoji of the button. This can be in string form or a PartialEmoji or a full Emoji.

  • 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 to None, 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 the discord.ui.View, the discord.ui.Select being pressed and the discord.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 of discord.ComponentType.string_select, discord.ComponentType.user_select, discord.ComponentType.role_select, discord.ComponentType.mentionable_select, or discord.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 to None, 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 the discord.ComponentType.string_select type.

  • channel_types (List[discord.ChannelType]) – The channel types that should be selectable. Only valid for the discord.ComponentType.channel_select type. Defaults to all channel types.

  • disabled (bool) – Whether the select is disabled or not. Defaults to False.

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 type discord.ComponentType.string_select.

New in version 2.3.

Parameters:
Return type:

Callable[[ItemCallbackType], ItemCallbackType]

@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 type discord.ComponentType.user_select.

New in version 2.3.

Parameters:
  • placeholder (str | None) –

  • custom_id (str | None) –

  • min_values (int) –

  • max_values (int) –

  • disabled (bool) –

  • row (int | None) –

Return type:

Callable[[ItemCallbackType], ItemCallbackType]

@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 type discord.ComponentType.role_select.

New in version 2.3.

Parameters:
  • placeholder (str | None) –

  • custom_id (str | None) –

  • min_values (int) –

  • max_values (int) –

  • disabled (bool) –

  • row (int | None) –

Return type:

Callable[[ItemCallbackType], ItemCallbackType]

@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 type discord.ComponentType.mentionable_select.

New in version 2.3.

Parameters:
  • placeholder (str | None) –

  • custom_id (str | None) –

  • min_values (int) –

  • max_values (int) –

  • disabled (bool) –

  • row (int | None) –

Return type:

Callable[[ItemCallbackType], ItemCallbackType]

@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 type discord.ComponentType.channel_select.

New in version 2.3.

Parameters:
  • placeholder (str | None) –

  • custom_id (str | None) –

  • min_values (int) –

  • max_values (int) –

  • disabled (bool) –

  • channel_types (list[ChannelType]) –

  • row (int | None) –

Return type:

Callable[[ItemCallbackType], ItemCallbackType]

Objects#

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:
  • *items (Item) – The initial items attached to this view.

  • timeout (Optional[float]) – Timeout in seconds from last interaction with the UI before no longer accepting input. If None 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]

children#

The list of children attached to this view.

Type:

List[Item]

disable_on_timeout#

Whether to disable the view when the timeout is reached. Defaults to False.

Type:

bool

message#

The message that this view is attached to. If None then the view has not been sent with a message.

Type:

Optional[Message]

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 the discord.ui namespace. In order to modify and edit message components they must be converted into a View first.

Parameters:
  • message (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:

View

add_item(item)[source]#

Adds an item to the view.

Parameters:

item (Item) – The item to add to the view.

Raises:
  • TypeError – An Item was not passed.

  • ValueError – Maximum number of children has been exceeded (25) or the row the item is trying to be added to is full.

Return type:

None

remove_item(item)[source]#

Removes an item from the view.

Parameters:

item (Item) – The item to remove from the view.

Return type:

None

clear_items()[source]#

Removes all items from the view.

Return type:

None

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).

Parameters:

custom_id (str) – The custom_id of the item to get

Returns:

The item with the matching custom_id if it exists.

Return type:

Optional[Item]

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:

bool

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:

None

await on_check_failure(interaction)[source]#

This function is a coroutine. A callback that is called when a View.interaction_check() returns False. This can be used to send a response when a check failure occurs.

Parameters:

interaction (Interaction) – The interaction that occurred.

Return type:

None

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:

None

stop()[source]#

Stops listening to interaction events from this view.

This operation cannot be undone.

Return type:

None

is_finished()[source]#

Whether the view has finished interacting.

Return type:

bool

is_dispatching()[source]#

Whether the view has been added for dispatching purposes.

Return type:

bool

is_persistent()[source]#

Whether the view is set up as persistent.

A persistent view has all their components with a set custom_id and a timeout set to None.

Return type:

bool

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. If False then the view finished normally.

Return type:

bool

disable_all_items(*, exclusions=None)[source]#

Disables all items in the view.

Parameters:

exclusions (Optional[List[Item]]) – A list of items in self.children to not disable from the view.

enable_all_items(*, exclusions=None)[source]#

Enables all items in the view.

Parameters:

exclusions (Optional[List[Item]]) – A list of items in self.children to not enable from the view.

Attributes
Methods
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.

Return type:

V | None

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.

Methods
class discord.ui.Button(*, style=<ButtonStyle.secondary: 2>, label=None, disabled=False, custom_id=None, url=None, emoji=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.

  • 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 to None, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).

property style#

The style of the button.

Return type:

ButtonStyle

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.

Return type:

str | None

property url#

The URL this button sends you to.

Return type:

str | None

property disabled#

Whether the button is disabled or not.

Return type:

bool

property label#

The label of the button, if available.

Return type:

str | None

property emoji#

The emoji of the button, if available.

Return type:

PartialEmoji | None

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.

Return type:

V | None

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.

Parameters:
property custom_id#

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

Return type:

str

property placeholder#

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

Return type:

str | None

property min_values#

The minimum number of items that must be chosen for this select menu.

Return type:

int

property max_values#

The maximum number of items that must be chosen for this select menu.

Return type:

int

property disabled#

Whether the select is disabled or not.

Return type:

bool

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 the append_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 of PartialEmoji or Emoji.

  • 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#

Union[List[str], List[Union[discord.Member, discord.User]], List[discord.Role]], List[Union[discord.Member, discord.User, discord.Role]], List[discord.abc.GuildChannel]]: A list of values that have been selected by the user.

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.

Return type:

V | None

Attributes
Methods
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. If None then there is no timeout.

property title#

The title of the modal dialog.

Return type:

str

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.

Return type:

str

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.

stop()[source]#

Stops listening to interaction events from the modal dialog.

Return type:

None

await wait()[source]#

Waits for the modal dialog to be submitted.

Return type:

bool

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:

None

await on_timeout()[source]#

This function is a coroutine.

A callback that is called when a modal’s timeout elapses without being explicitly stopped.

Return type:

None

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 to True.

  • 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 to None, 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.

Return type:

InputTextStyle

property custom_id#

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

Return type:

str

property label#

The label of the input text field.

Return type:

str

property placeholder#

The placeholder text that is shown before anything is entered, if any.

Return type:

str | None

property min_length#

The minimum number of characters that must be entered. Defaults to 0.

Return type:

int | None

property max_length#

The maximum number of characters that can be entered.

Return type:

int | None

property required#

Whether the input text field is required or not. Defaults to True.

Return type:

bool | None

property value#

The value entered in the text field.

Return type:

str | None