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=('secondary', 2), emoji=None, row=None, id=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, discord.ui.ActionRow or discord.ui.Section, the discord.ui.Button being pressed, and the discord.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 to ButtonStyle.grey.

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

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

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

    Warning

    This parameter does not work in ActionRow.

  • id (int | None)

Return type:

Callable[[Callable[[Any, Button[TypeVar(V, bound= BaseView, covariant=True)], Interaction], Coroutine[Any, Any, Any]]], Button[TypeVar(V, bound= BaseView, covariant=True)]]

@discord.ui.select(select_type=('string_select', 3), *, placeholder=None, custom_id=None, min_values=1, max_values=1, options=..., channel_types=..., disabled=False, row=None, id=None, default_values=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, discord.ui.ActionRow or discord.ui.Section, 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:
Return type:

Callable[[Callable[[Any, Select[TypeVar(V, bound= BaseView, covariant=True), TypeVar(ST, bound= Snowflake | str, covariant=True), Any], Interaction], Coroutine[Any, Any, Any]]], Select[TypeVar(V, bound= BaseView, covariant=True), TypeVar(ST, bound= Snowflake | str, covariant=True), Any]]

@discord.ui.string_select(*, placeholder=None, custom_id=None, min_values=1, max_values=1, options=..., disabled=False, row=None, id=None)[source]

A shortcut for discord.ui.select() with select type discord.ComponentType.string_select.

Added in version 2.3.

Parameters:
Return type:

Callable[[Callable[[Any, Select[TypeVar(V, bound= BaseView, covariant=True), str, Any], Interaction], Coroutine[Any, Any, Any]]], Select[TypeVar(V, bound= BaseView, covariant=True), str, Any]]

@discord.ui.user_select(*, placeholder=None, custom_id=None, min_values=1, max_values=1, disabled=False, row=None, id=None, default_values=None)[source]

A shortcut for discord.ui.select() with select type discord.ComponentType.user_select.

Added in version 2.3.

Parameters:
Return type:

Callable[[Callable[[Any, Select[TypeVar(V, bound= BaseView, covariant=True), User | Member, Any], Interaction], Coroutine[Any, Any, Any]]], Select[TypeVar(V, bound= BaseView, covariant=True), User | Member, Any]]

@discord.ui.role_select(*, placeholder=None, custom_id=None, min_values=1, max_values=1, disabled=False, row=None, id=None, default_values=None)[source]

A shortcut for discord.ui.select() with select type discord.ComponentType.role_select.

Added in version 2.3.

Parameters:
Return type:

Callable[[Callable[[Any, Select[TypeVar(V, bound= BaseView, covariant=True), Role, Any], Interaction], Coroutine[Any, Any, Any]]], Select[TypeVar(V, bound= BaseView, covariant=True), Role, Any]]

@discord.ui.mentionable_select(*, placeholder=None, custom_id=None, min_values=1, max_values=1, disabled=False, row=None, id=None, default_values=None)[source]

A shortcut for discord.ui.select() with select type discord.ComponentType.mentionable_select.

Added in version 2.3.

Parameters:
Return type:

Callable[[Callable[[Any, Select[TypeVar(V, bound= BaseView, covariant=True), User | Member | Role, Any], Interaction], Coroutine[Any, Any, Any]]], Select[TypeVar(V, bound= BaseView, covariant=True), User | Member | Role, Any]]

@discord.ui.channel_select(*, placeholder=None, custom_id=None, min_values=1, max_values=1, disabled=False, channel_types=..., row=None, id=None, default_values=None)[source]

A shortcut for discord.ui.select() with select type discord.ComponentType.channel_select.

Added in version 2.3.

Parameters:
Return type:

Callable[[Callable[[Any, Select[TypeVar(V, bound= BaseView, covariant=True), GuildChannel | Thread, Any], Interaction], Coroutine[Any, Any, Any]]], Select[TypeVar(V, bound= BaseView, covariant=True), GuildChannel | Thread, Any]]

Objects

Methods
class discord.ui.BaseView(*items, timeout=180.0, disable_on_timeout=False, store=True)[source]

The base class for UI views used in messages.

Added in version 2.7.

Parameters:
add_item(item)[source]

Adds an item to the view.

Parameters:

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

Raises:
Return type:

Self

remove_item(item)[source]

Removes an item from the view. If an int or str is passed, the item will be removed by ViewItem id or custom_id respectively.

Parameters:

item (Union[ViewItem, int, str]) – The item, item id, or item custom_id to remove from the view.

Returns:

The view instance.

Return type:

BaseView

clear_items()[source]

Removes all items from this view.

Return type:

Self

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 BaseView.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 (ViewItem) – The item that failed the dispatch.

  • interaction (Interaction) – The interaction that led to the failure.

Return type:

None

is_components_v2()[source]

Whether the view contains V2 components.

A view containing V2 components cannot be sent alongside message content or embeds.

Return type:

bool

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

stop()[source]

Stops listening to interaction events from this view.

This operation cannot be undone.

Return type:

None

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 buttons and select menus in the view.

Parameters:

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

Return type:

Self

enable_all_items(*, exclusions=None)[source]

Enables all buttons and select menus in the view.

Parameters:

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

Return type:

Self

copy_text()[source]

Returns the text of all TextDisplay items in this View. Equivalent to the Copy Text option on Discord clients.

Return type:

str

Attributes
Methods
class discord.ui.View(*items, timeout=180.0, disable_on_timeout=False, store=True)[source]

Represents a legacy UI view for V1 components Button and Select.

This object must be inherited to create a UI within Discord.

Added in version 2.0.

Changed in version 2.7: Now inherits from BaseView

Parameters:

  • *items (ViewItem) – The initial items attached to this view.

  • timeout (Optional[float]) – Timeout in seconds from last interaction with the UI before no longer accepting input. Defaults to 180.0. If None then there is no timeout.

  • store (Optional[bool]) – Whether this view should be stored for callback listening. Setting it to False will ignore item callbacks and prevent their values from being refreshed. Defaults to True.

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[ViewItem]

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]

parent

The parent interaction which this view was sent from. If None then the view was not sent using InteractionResponse.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 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

classmethod from_dict(data, /, *, timeout=180.0)[source]

Converts a list of component dicts into a View.

Parameters:

  • data (List[Component]) – The list of 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. Attempting to add a ActionRow will add its children instead.

Parameters:

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

Raises:

  • TypeError – An ViewItem 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:

Self

remove_item(item)[source]

Removes an item from the view. If an int or str is passed, the item will be removed by Item id or custom_id respectively.

Parameters:

item (Union[ViewItem, int, str]) – The item, item id, or item custom_id to remove from the view.

Return type:

Self

clear_items()[source]

Removes all items from the view.

Return type:

Self

is_components_v2()[source]

Whether the view contains V2 components.

A view containing V2 components cannot be sent alongside message content or embeds.

This is always False for View.

Return type:

bool

copy_text()

Returns the text of all TextDisplay items in this View. Equivalent to the Copy Text option on Discord clients.

Return type:

str

disable_all_items(*, exclusions=None)

Disables all buttons and select menus in the view.

Parameters:

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

Return type:

Self

enable_all_items(*, exclusions=None)

Enables all buttons and select menus in the view.

Parameters:

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

Return type:

Self

get_item(custom_id)

Gets an item from this structure. Roughly equal to utils.get(self.children, …). If an int is provided, the item will be retrieved by id, otherwise by custom_id. This method will also search nested items.

Parameters:

custom_id (Union[str, int]) – The id of the item to get

Returns:

The item with the matching custom_id or id if it exists.

Return type:

Optional[Item]

await interaction_check(interaction)

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

is_dispatching()

Whether the view has been added for dispatching purposes.

Return type:

bool

is_finished()

Whether the view has finished interacting.

Return type:

bool

is_persistent()

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 on_check_failure(interaction)

This function is a coroutine. A callback that is called when a BaseView.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)

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 (ViewItem) – The item that failed the dispatch.

  • interaction (Interaction) – The interaction that led to the failure.

Return type:

None

await on_timeout()

This function is a coroutine.

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

Return type:

None

stop()

Stops listening to interaction events from this view.

This operation cannot be undone.

Return type:

None

await wait()

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

Attributes
Methods
class discord.ui.DesignerView(*items, timeout=180.0, disable_on_timeout=False, store=True)[source]

Represents a UI view compatible with v2 components.

This object must be inherited to create a UI within Discord.

Added in version 2.7.

Parameters:

  • *items (ViewItem) – The initial items attached to this view.

  • timeout (Optional[float]) – Timeout in seconds from last interaction with the UI before no longer accepting input. Defaults to 180.0. If None then there is no timeout.

  • store (Optional[bool]) – Whether this view should be stored for callback listening. Setting it to False will ignore item callbacks and prevent their values from being refreshed. Defaults to True.

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 items attached to this view.

Type:

List[ViewItem]

disable_on_timeout

Whether to disable the view’s items 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]

parent

The parent interaction which this view was sent from. If None then the view was not sent using InteractionResponse.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 DesignerView.

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

classmethod from_dict(data, /, *, timeout=180.0)[source]

Converts a list of component dicts into a DesignerView.

Parameters:

  • data (List[Component]) – The list of 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:

DesignerView

add_item(item)[source]

Adds an item to the view.

Parameters:

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

Raises:
Return type:

Self

is_components_v2()[source]

Whether the view contains V2 components.

A view containing V2 components cannot be sent alongside message content or embeds.

Return type:

bool

clear_items()

Removes all items from this view.

Return type:

Self

copy_text()

Returns the text of all TextDisplay items in this View. Equivalent to the Copy Text option on Discord clients.

Return type:

str

disable_all_items(*, exclusions=None)

Disables all buttons and select menus in the view.

Parameters:

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

Return type:

Self

enable_all_items(*, exclusions=None)

Enables all buttons and select menus in the view.

Parameters:

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

Return type:

Self

get_item(custom_id)

Gets an item from this structure. Roughly equal to utils.get(self.children, …). If an int is provided, the item will be retrieved by id, otherwise by custom_id. This method will also search nested items.

Parameters:

custom_id (Union[str, int]) – The id of the item to get

Returns:

The item with the matching custom_id or id if it exists.

Return type:

Optional[Item]

await interaction_check(interaction)

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

is_dispatching()

Whether the view has been added for dispatching purposes.

Return type:

bool

is_finished()

Whether the view has finished interacting.

Return type:

bool

is_persistent()

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 on_check_failure(interaction)

This function is a coroutine. A callback that is called when a BaseView.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)

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 (ViewItem) – The item that failed the dispatch.

  • interaction (Interaction) – The interaction that led to the failure.

Return type:

None

await on_timeout()

This function is a coroutine.

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

Return type:

None

remove_item(item)

Removes an item from the view. If an int or str is passed, the item will be removed by ViewItem id or custom_id respectively.

Parameters:

item (Union[ViewItem, int, str]) – The item, item id, or item custom_id to remove from the view.

Returns:

The view instance.

Return type:

BaseView

stop()

Stops listening to interaction events from this view.

This operation cannot be undone.

Return type:

None

await wait()

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

Attributes
class discord.ui.Item[source]

Represents the base UI item that all UI components inherit from.

Added in version 2.0.

Changed in version 2.7: Now used as base class for ViewItem and ModalItem.

property id: int | None

Gets this item’s ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item’s parent is sent.

Returns:

The ID of this item, or None if the user didn’t set one.

Return type:

Optional[int]

Attributes
Methods
class discord.ui.ViewItem[source]

Represents an item used in Views.

The following are the original items supported in discord.ui.View:

And the following are new items under the “Components V2” specification for use in discord.ui.DesignerView:

Additionally, discord.ui.ActionRow should be used in discord.ui.DesignerView to support discord.ui.Button and discord.ui.Select.

Added in version 2.7.

property view: V | None

Gets the parent view associated with this item.

The view refers to the structure that holds this item. This is typically set automatically when the item is added to a view.

Returns:

The parent view of this item, or None if the item is not attached to any view.

Return type:

Optional[BaseView]

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.

property id: int | None

Gets this item’s ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item’s parent is sent.

Returns:

The ID of this item, or None if the user didn’t set one.

Return type:

Optional[int]

Attributes
class discord.ui.ModalItem[source]

Represents an item used in Modals.

discord.ui.InputText is the original item supported in discord.ui.Modal.

The following are newly available in discord.ui.DesignerModal:

And discord.ui.Label should be used in discord.ui.DesignerModal to support the following items: - discord.ui.InputText - discord.ui.Select - discord.ui.FileUpload

Added in version 2.7.

property id: int | None

Gets this item’s ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item’s parent is sent.

Returns:

The ID of this item, or None if the user didn’t set one.

Return type:

Optional[int]

property modal: M | None

Gets the parent modal associated with this item. This is typically set automatically when the item is added to a modal.

Returns:

The parent modal of this item, or None if the item is not attached to any modal.

Return type:

Optional[BaseModal]

Attributes
Methods
class discord.ui.ActionRow(*items, id=None)[source]

Represents a UI Action Row used in discord.ui.DesignerView.

The items supported are as follows:

Added in version 2.7.

Parameters:

  • *items (ViewItem) – The initial items in this action row.

  • id (Optional[int]) – The action’s ID.

add_item(item)[source]

Adds an item to the action row.

Parameters:

item (ViewItem) – The item to add to the action row.

Raises:

TypeError – A ViewItem was not passed.

Return type:

Self

remove_item(item)[source]

Removes an item from the action row. If an int or str is passed, it will remove by Item id or custom_id respectively.

Parameters:

item (Union[ViewItem, int, str]) – The item, id, or item custom_id to remove from the action row.

Return type:

Self

get_item(id)[source]

Get an item from this action row. Roughly equivalent to utils.get(row.children, …). If an int is provided, the item will be retrieved by id, otherwise by custom_id.

Parameters:

id (Union[str, int]) – The id or custom_id of the item to get.

Returns:

The item with the matching id or custom_id if it exists.

Return type:

Optional[ViewItem]

add_button(*, style=('secondary', 2), label=None, disabled=False, custom_id=None, url=None, emoji=None, sku_id=None, id=None)[source]

Adds a Button to the action row.

To append a pre-existing Button, use the add_item() method instead.

Parameters:

  • style (discord.ButtonStyle) – The style of the button.

  • custom_id (Optional[str]) – The custom 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, GuildEmoji, AppEmoji, str]]) – The emoji of the button, if any.

  • sku_id (Optional[Union[int]]) – The ID of the SKU this button refers to.

  • id (Optional[int]) – The button’s ID.

Return type:

Self

add_select(select_type=('string_select', 3), *, custom_id=None, placeholder=None, min_values=1, max_values=1, options=None, channel_types=None, disabled=False, id=None, default_values=None)[source]

Adds a Select to the action row.

To append a pre-existing Select, use the add_item() method instead.

Parameters:
Return type:

Self

disable_all_items(*, exclusions=None)[source]

Disables all items in the row.

Parameters:

exclusions (Optional[List[ViewItem]]) – A list of items in self.children to not disable.

Return type:

Self

enable_all_items(*, exclusions=None)[source]

Enables all items in the row.

Parameters:

exclusions (Optional[List[ViewItem]]) – A list of items in self.children to not enable.

Return type:

Self

property width

Return the sum of the items’ widths.

property id: int | None

Gets this item’s ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item’s parent is sent.

Returns:

The ID of this item, or None if the user didn’t set one.

Return type:

Optional[int]

property view: V | None

Gets the parent view associated with this item.

The view refers to the structure that holds this item. This is typically set automatically when the item is added to a view.

Returns:

The parent view of this item, or None if the item is not attached to any view.

Return type:

Optional[BaseView]

Attributes
Methods
class discord.ui.Button(*, style=('secondary', 2), label=None, disabled=False, custom_id=None, url=None, emoji=None, sku_id=None, row=None, id=None)[source]

Represents a UI button.

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

    Warning

    This parameter does not work in ActionRow.

  • id (Optional[int]) – The button’s ID.

property style: ButtonStyle

The style of the button.

property custom_id: str | None

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: str | None

The URL this button sends you to.

property disabled: bool

Whether the button is disabled or not.

property label: str | None

The label of the button, if available.

property emoji: PartialEmoji | None

The emoji of the button, if available.

property sku_id: int | None

The ID of the SKU this button refers to.

property width: int

Gets the width of the item in the UI layout.

The width determines how much horizontal space this item occupies within its row.

Returns:

The width of the item. Buttons have a width of 1.

Return type:

int

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 id: int | None

Gets this item’s ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item’s parent is sent.

Returns:

The ID of this item, or None if the user didn’t set one.

Return type:

Optional[int]

property view: V | None

Gets the parent view associated with this item.

The view refers to the structure that holds this item. This is typically set automatically when the item is added to a view.

Returns:

The parent view of this item, or None if the item is not attached to any view.

Return type:

Optional[BaseView]

property row: int | None

Gets or sets the row position of this item within its parent view.

The row position determines the vertical placement of the item in the UI. The value must be an integer between 0 and 4 (inclusive), or None to indicate that no specific row is set. This attribute is not compatible with discord.ui.DesignerView.

Returns:

The row position of the item, or None if not explicitly set.

Return type:

Optional[int]

Raises:

ValueError – If the row value is not None and is outside the range [0, 4].

Attributes
Methods
class discord.ui.Select(select_type=('string_select', 3), *, custom_id=None, placeholder=None, min_values=1, max_values=1, options=None, channel_types=None, disabled=False, row=None, id=None, required=None, default_values=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.

Added 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, and discord.ComponentType.channel_select.

Changed in version 2.7: Can now be sent in discord.ui.DesignerModal.

Parameters:
property custom_id: str

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

property placeholder: str | None

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

property min_values: int

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

property max_values: int

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

property required: bool

Whether the select is required or not. Only applicable in modal selects.

property disabled: bool

Whether the select is disabled or not.

property channel_types: list[ChannelType]

A list of channel types that can be selected in this menu.

property options: list[SelectOption]

A list of options that can be selected in this menu.

property default_values: list[SelectDefaultValue]

A list of the select’s default values. This is only applicable if the select type is not discord.ComponentType.string_select.

Added in version 2.7.

add_default_value(*, id, type=...)[source]

Adds a default value to the select menu.

To append a pre-existing discord.SelectDefaultValue use the append_default_value() method instead.

Added in version 2.7.

Parameters:
Raises:

  • TypeError – The select type is a mentionable_select and type was not provided, or the select type is string_select.

  • ValueError – The number of default select values exceeds 25.

Return type:

Self

append_default_value(value, /)[source]

Appends a default value to this select menu.

Added in version 2.7.

Parameters:

value (Union[discord.SelectDefaultValue, discord.abc.Snowflake]) –

The default value to append to this select.

These can be either discord.SelectDefaultValue instances or models, which will be converted into discord.SelectDefaultvalue instances.

Below, is a table defining the model instance type and the default value type it will be mapped:

Model Type

Default Value Type

discord.User

discord.SelectDefaultValueType.user

discord.Member

discord.SelectDefaultValueType.user

discord.Role

discord.SelectDefaultValueType.role

discord.abc.GuildChannel

discord.SelectDefaultValueType.channel

discord.Object

depending on discord.Object.type, it will be mapped to any above

If you pass a model that is not defined in the table, TypeError will be raised.

Note

The discord.abc.GuildChannel protocol includes discord.TextChannel, discord.VoiceChannel, discord.StageChannel, discord.ForumChannel, discord.Thread, discord.MediaChannel. This list is not exhaustive, and is bound to change based of the new channel types Discord adds.

Raises:

  • TypeError – The select type is string_select, which does not allow for default_values

  • ValueError – The number of default select values exceeds 25.

Return type:

Self

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, GuildEmoji, AppEmoji, 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, GuildEmoji, or AppEmoji.

  • default (bool) – Whether this option is selected by default.

Raises:

ValueError – The number of options exceeds 25.

Return type:

Self

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.

Return type:

Self

property values: list[ST]

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 be None if the select has not been interacted with yet.

property width: int

Gets the width of the item in the UI layout.

The width determines how much horizontal space this item occupies within its row.

Returns:

The width of the item. Select menus have a width of 5.

Return type:

int

property row: int | None

Gets or sets the row position of this item within its parent view.

The row position determines the vertical placement of the item in the UI. The value must be an integer between 0 and 4 (inclusive), or None to indicate that no specific row is set. This attribute is not compatible with discord.ui.DesignerView.

Returns:

The row position of the item, or None if not explicitly set.

Return type:

Optional[int]

Raises:

ValueError – If the row value is not None and is outside the range [0, 4].

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 id: int | None

Gets this item’s ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item’s parent is sent.

Returns:

The ID of this item, or None if the user didn’t set one.

Return type:

Optional[int]

property modal: M | None

Gets the parent modal associated with this item. This is typically set automatically when the item is added to a modal.

Returns:

The parent modal of this item, or None if the item is not attached to any modal.

Return type:

Optional[BaseModal]

property view: V | None

Gets the parent view associated with this item.

The view refers to the structure that holds this item. This is typically set automatically when the item is added to a view.

Returns:

The parent view of this item, or None if the item is not attached to any view.

Return type:

Optional[BaseView]

class discord.ui.StringSelect

An alias for Select with select_type as discord.ComponentType.string_select.

class discord.ui.UserSelect

An alias for Select with select_type as discord.ComponentType.user_select.

class discord.ui.RoleSelect

An alias for Select with select_type as discord.ComponentType.role_select.

class discord.ui.MentionableSelect

An alias for Select with select_type as discord.ComponentType.mentionable_select.

class discord.ui.ChannelSelect

An alias for Select with select_type as discord.ComponentType.channel_select.

Attributes
Methods
class discord.ui.Section(*items, accessory=None, id=None)[source]

Represents a UI section. Sections must have 1-3 (inclusive) items and an accessory set.

Added in version 2.7.

Parameters:

  • *items (ViewItem) – The initial items contained in this section, up to 3. Currently only supports TextDisplay. Sections must have at least 1 item before being sent.

  • accessory (Optional[ViewItem]) – The section’s accessory. This is displayed in the top right of the section. Currently only supports Button and Thumbnail. Sections must have an accessory attached before being sent.

  • id (Optional[int]) – The section’s ID.

items

The list of items in this section.

Type:

List[ViewItem]

accessory

The section’s accessory, displayed in the top right of the section.

Type:

ViewItem

add_item(item)[source]

Adds an item to the section.

Parameters:

item (ViewItem) – The item to add to the section.

Raises:
Return type:

Self

remove_item(item)[source]

Removes an item from the section. If an int or str is passed, the item will be removed by Item id or custom_id respectively.

Parameters:

item (Union[ViewItem, int, str]) – The item, item id, or item custom_id to remove from the section.

Return type:

Self

get_item(id)[source]

Get an item from this section. Alias for utils.get(section.walk_items(), …). If an int is provided, it will be retrieved by id, otherwise it will check the accessory’s custom_id.

Parameters:

id (Union[str, int]) – The id or custom_id of the item to get.

Returns:

The item with the matching id if it exists.

Return type:

Optional[ViewItem]

add_text(content, *, id=None)[source]

Adds a TextDisplay to the section.

Parameters:

  • content (str) – The content of the text display.

  • id (Optional[int]) – The text display’s ID.

Raises:

ValueError – Maximum number of items has been exceeded (3).

Return type:

Self

set_accessory(item)[source]

Set an item as the section’s accessory.

Parameters:

item (ViewItem) – The item to set as accessory. Currently only supports Button and Thumbnail.

Raises:

TypeError – An ViewItem was not passed.

Return type:

Self

set_thumbnail(url, *, description=None, spoiler=False, id=None)[source]

Sets a Thumbnail with the provided URL as the section’s accessory.

Parameters:

  • url (str) – The url of the thumbnail.

  • description (Optional[str]) – The thumbnail’s description, up to 1024 characters.

  • spoiler (Optional[bool]) – Whether the thumbnail has the spoiler overlay. Defaults to False.

  • id (Optional[int]) – The thumbnail’s ID.

Return type:

Self

copy_text()[source]

Returns the text of all TextDisplay items in this section. Equivalent to the Copy Text option on Discord clients.

Return type:

str

disable_all_items(*, exclusions=None)[source]

Disables all buttons and select menus in the section. At the moment, this only disables accessory if it is a button.

Parameters:

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

Return type:

Self

enable_all_items(*, exclusions=None)[source]

Enables all buttons and select menus in the section. At the moment, this only enables accessory if it is a button.

Parameters:

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

Return type:

Self

property id: int | None

Gets this item’s ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item’s parent is sent.

Returns:

The ID of this item, or None if the user didn’t set one.

Return type:

Optional[int]

property view: V | None

Gets the parent view associated with this item.

The view refers to the structure that holds this item. This is typically set automatically when the item is added to a view.

Returns:

The parent view of this item, or None if the item is not attached to any view.

Return type:

Optional[BaseView]

Attributes
Methods
class discord.ui.TextDisplay(content, id=None)[source]

Represents a UI text display. A message can have up to 4000 characters across all TextDisplay objects combined.

Added in version 2.7.

Parameters:

  • content (str) – The text display’s content, up to 4000 characters.

  • id (Optional[int]) – The text display’s ID.

property content: str

The text display’s content.

copy_text()[source]

Returns the content of this text display. Equivalent to the Copy Text option on Discord clients.

Return type:

str

property id: int | None

Gets this item’s ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item’s parent is sent.

Returns:

The ID of this item, or None if the user didn’t set one.

Return type:

Optional[int]

property modal: M | None

Gets the parent modal associated with this item. This is typically set automatically when the item is added to a modal.

Returns:

The parent modal of this item, or None if the item is not attached to any modal.

Return type:

Optional[BaseModal]

property view: V | None

Gets the parent view associated with this item.

The view refers to the structure that holds this item. This is typically set automatically when the item is added to a view.

Returns:

The parent view of this item, or None if the item is not attached to any view.

Return type:

Optional[BaseView]

Attributes
class discord.ui.Thumbnail(url, *, description=None, spoiler=False, id=None)[source]

Represents a UI Thumbnail.

Added in version 2.7.

Parameters:

  • url (str) – The url of the thumbnail. This can either be an arbitrary URL or an attachment:// URL to work with local files.

  • description (Optional[str]) – The thumbnail’s description, up to 1024 characters.

  • spoiler (Optional[bool]) – Whether the thumbnail has the spoiler overlay. Defaults to False.

  • id (Optional[int]) – The thumbnail’s ID.

property media: UnfurledMediaItem

The thumbnail’s unerlying media item.

property url: str

The URL of this thumbnail’s media. This can either be an arbitrary URL or an attachment:// URL.

property description: str | None

The thumbnail’s description, up to 1024 characters.

property id: int | None

Gets this item’s ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item’s parent is sent.

Returns:

The ID of this item, or None if the user didn’t set one.

Return type:

Optional[int]

property spoiler: bool

Whether the thumbnail has the spoiler overlay. Defaults to False.

property view: V | None

Gets the parent view associated with this item.

The view refers to the structure that holds this item. This is typically set automatically when the item is added to a view.

Returns:

The parent view of this item, or None if the item is not attached to any view.

Return type:

Optional[BaseView]

Attributes
Methods
class discord.ui.MediaGallery(*items, id=None)[source]

Represents a UI Media Gallery. Galleries may contain up to 10 MediaGalleryItem objects.

Added in version 2.7.

Parameters:

  • *items (MediaGalleryItem) – The initial items contained in this gallery, up to 10.

  • id (Optional[int]) – The gallery’s ID.

items

The list of media items in this gallery.

Type:

List[MediaGalleryItem]

property items: list[MediaGalleryItem]

The list of media items in this gallery.

append_item(item)[source]

Adds a MediaGalleryItem to the gallery.

Parameters:

item (MediaGalleryItem) – The gallery item to add to the gallery.

Raises:

  • TypeError – A MediaGalleryItem was not passed.

  • ValueError – Maximum number of items has been exceeded (10).

Return type:

Self

add_item(url, *, description=None, spoiler=False)[source]

Adds a new media item to the gallery.

Parameters:

  • url (str) – The URL of the media item. This can either be an arbitrary URL or an attachment:// URL.

  • description (Optional[str]) – The media item’s description, up to 1024 characters.

  • spoiler (Optional[bool]) – Whether the media item has the spoiler overlay.

Raises:

ValueError – Maximum number of items has been exceeded (10).

Return type:

Self

remove_item(index)[source]

Removes an item from the gallery.

Parameters:

index (int) – The index of the item to remove from the gallery.

Return type:

Self

property id: int | None

Gets this item’s ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item’s parent is sent.

Returns:

The ID of this item, or None if the user didn’t set one.

Return type:

Optional[int]

property view: V | None

Gets the parent view associated with this item.

The view refers to the structure that holds this item. This is typically set automatically when the item is added to a view.

Returns:

The parent view of this item, or None if the item is not attached to any view.

Return type:

Optional[BaseView]

Attributes
class discord.ui.File(url, *, spoiler=False, id=None)[source]

Represents a UI File.

Note

This component does not show media previews. Use MediaGallery for previews instead.

Added in version 2.7.

Parameters:

  • url (str) – The URL of this file. This must be an attachment:// URL referring to a local file used with File.

  • spoiler (Optional[bool]) – Whether this file has the spoiler overlay.

  • id (Optional[int]) – The file component’s ID.

property file: UnfurledMediaItem

The file’s unerlying media item.

property url: str

The URL of this file’s underlying media. This must be an attachment:// URL that references a File.

property spoiler: bool

Whether the file has the spoiler overlay. Defaults to False.

property name: str

The name of this file, if provided by Discord.

property size: int

The size of this file in bytes, if provided by Discord.

property id: int | None

Gets this item’s ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item’s parent is sent.

Returns:

The ID of this item, or None if the user didn’t set one.

Return type:

Optional[int]

property view: V | None

Gets the parent view associated with this item.

The view refers to the structure that holds this item. This is typically set automatically when the item is added to a view.

Returns:

The parent view of this item, or None if the item is not attached to any view.

Return type:

Optional[BaseView]

Attributes
class discord.ui.Separator(*, divider=True, spacing=('small', 1), id=None)[source]

Represents a UI Separator.

Added in version 2.7.

Parameters:

  • divider (bool) – Whether the separator is a divider. Defaults to True.

  • spacing (SeparatorSpacingSize) – The spacing size of the separator. Defaults to small.

  • id (Optional[int]) – The separator’s ID.

property divider: bool

Whether the separator is a divider. Defaults to True.

property spacing: SeparatorSpacingSize

The spacing size of the separator. Defaults to small.

property id: int | None

Gets this item’s ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item’s parent is sent.

Returns:

The ID of this item, or None if the user didn’t set one.

Return type:

Optional[int]

property view: V | None

Gets the parent view associated with this item.

The view refers to the structure that holds this item. This is typically set automatically when the item is added to a view.

Returns:

The parent view of this item, or None if the item is not attached to any view.

Return type:

Optional[BaseView]

Attributes
Methods
class discord.ui.Container(*items, colour=None, color=None, spoiler=False, id=None)[source]

Represents a UI Container.

The current items supported are as follows:

Added in version 2.7.

Parameters:

  • *items (ViewItem) – The initial items in this container.

  • colour (Union[Colour, int]) – The accent colour of the container. Aliased to color as well.

  • spoiler (Optional[bool]) – Whether this container has the spoiler overlay.

  • id (Optional[int]) – The container’s ID.

items

The list of items in this container.

Type:

List[ViewItem]

Parameters:

color (int | Colour | None)

add_item(item)[source]

Adds an item to the container.

Parameters:

item (ViewItem) – The item to add to the container.

Raises:

TypeError – A ViewItem was not passed.

Return type:

Self

remove_item(item)[source]

Removes an item from the container. If an int or str is passed, it will remove by Item id or custom_id respectively.

Parameters:

item (Union[ViewItem, int, str]) – The item, id, or item custom_id to remove from the container.

Return type:

Self

get_item(id)[source]

Get an item from this container. Roughly equivalent to utils.get(container.items, …). If an int is provided, the item will be retrieved by id, otherwise by custom_id. This method will also search for nested items.

Parameters:

id (Union[str, int]) – The id or custom_id of the item to get.

Returns:

The item with the matching id or custom_id if it exists.

Return type:

Optional[ViewItem]

add_row(*items, id=None)[source]

Adds an ActionRow to the container.

To append a pre-existing ActionRow, use add_item() instead.

Parameters:

  • *items (Union[Button, Select]) – The items this action row contains.

  • id (Optiona[int]) – The action row’s ID.

Return type:

Self

add_section(*items, accessory, id=None)[source]

Adds a Section to the container.

To append a pre-existing Section, use the add_item() method, instead.

Parameters:

  • *items (ViewItem) – The items contained in this section, up to 3. Currently only supports TextDisplay.

  • accessory (Optional[ViewItem]) – The section’s accessory. This is displayed in the top right of the section. Currently only supports Button and Thumbnail.

  • id (Optional[int]) – The section’s ID.

Return type:

Self

add_text(content, id=None)[source]

Adds a TextDisplay to the container.

Parameters:

  • content (str) – The content of the TextDisplay

  • id (Optiona[int]) – The text displays’ ID.

Return type:

Self

Adds a MediaGallery to the container.

To append a pre-existing MediaGallery, use add_item() instead.

Parameters:

  • *items (MediaGalleryItem) – The media this gallery contains.

  • id (Optiona[int]) – The gallery’s ID.

Return type:

Self

add_file(url, spoiler=False, id=None)[source]

Adds a TextDisplay to the container.

Parameters:

  • url (str) – The URL of this file’s media. This must be an attachment:// URL that references a File.

  • spoiler (Optional[bool]) – Whether the file has the spoiler overlay. Defaults to False.

  • id (Optiona[int]) – The file’s ID.

Return type:

Self

add_separator(*, divider=True, spacing=('small', 1), id=None)[source]

Adds a Separator to the container.

Parameters:

  • divider (bool) – Whether the separator is a divider. Defaults to True.

  • spacing (SeparatorSpacingSize) – The spacing size of the separator. Defaults to small.

  • id (Optional[int]) – The separator’s ID.

Return type:

Self

copy_text()[source]

Returns the text of all TextDisplay items in this container. Equivalent to the Copy Text option on Discord clients.

Return type:

str

property spoiler: bool

Whether the container has the spoiler overlay. Defaults to False.

disable_all_items(*, exclusions=None)[source]

Disables all buttons and select menus in the container.

Parameters:

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

Return type:

Self

enable_all_items(*, exclusions=None)[source]

Enables all buttons and select menus in the container.

Parameters:

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

Return type:

Self

property id: int | None

Gets this item’s ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item’s parent is sent.

Returns:

The ID of this item, or None if the user didn’t set one.

Return type:

Optional[int]

property view: V | None

Gets the parent view associated with this item.

The view refers to the structure that holds this item. This is typically set automatically when the item is added to a view.

Returns:

The parent view of this item, or None if the item is not attached to any view.

Return type:

Optional[BaseView]

Attributes
Methods
class discord.ui.BaseModal(*children, title, custom_id=None, timeout=None, store=True)[source]

The base class for creating pop-up modals.

Added in version 2.7.

Parameters:
property title: str

The title of the modal.

property children: list[ModalItem]

The child items attached to the modal.

property custom_id: str

The ID of the modal that gets received during an interaction.

await callback(interaction)[source]

This function is a coroutine.

The coroutine that is called when the modal is submitted. Should be overridden to handle the values submitted by the user.

Parameters:

interaction (Interaction) – The interaction that submitted the modal.

add_item(item)[source]

Adds a component to the modal.

Parameters:

item (Union[ModalItem]) – The item to add to the modal

Return type:

Self

remove_item(item)[source]

Removes a component from the modal.

Parameters:

item (ModalItem) – The item to remove from the modal.

Return type:

Self

stop()[source]

Stops listening to interaction events from the modal.

Return type:

None

await wait()[source]

Waits for the modal 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

get_item(custom_id)

Gets an item from this structure. Roughly equal to utils.get(self.children, …). If an int is provided, the item will be retrieved by id, otherwise by custom_id. This method will also search nested items.

Parameters:

custom_id (Union[str, int]) – The id of the item to get

Returns:

The item with the matching custom_id or id if it exists.

Return type:

Optional[Item]

Attributes
Methods
class discord.ui.Modal(*children, title, custom_id=None, timeout=None, store=True)[source]

Represents a legacy UI modal for InputText components.

This object must be inherited to create a UI within Discord.

Added in version 2.0.

Changed in version 2.7: Now inherits from BaseModal

Parameters:

  • children (Union[InputText]) – The initial items that are displayed in the modal. Only supports discord.ui.InputText; for newer modal features, see DesignerModal.

  • title (str) – The title of the modal. Must be 45 characters or fewer.

  • custom_id (Optional[str]) – The ID of the modal 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.

  • store (Optional[bool]) – Whether this modal should be stored for callback listening. Setting it to False will ignore its callback and prevent item values from being refreshed. Defaults to True.

property children: list[InputText]

The child items attached to the modal.

add_item(item)[source]

Adds an InputText component to the modal.

Parameters:

item (InputText) – The item to add to the modal

Return type:

Self

remove_item(item)[source]

Removes an InputText from the modal.

Parameters:

item (Union[class:InputText]) – The item to remove from the modal.

Return type:

Self

await callback(interaction)

This function is a coroutine.

The coroutine that is called when the modal is submitted. Should be overridden to handle the values submitted by the user.

Parameters:

interaction (Interaction) – The interaction that submitted the modal.

property custom_id: str

The ID of the modal that gets received during an interaction.

get_item(custom_id)

Gets an item from this structure. Roughly equal to utils.get(self.children, …). If an int is provided, the item will be retrieved by id, otherwise by custom_id. This method will also search nested items.

Parameters:

custom_id (Union[str, int]) – The id of the item to get

Returns:

The item with the matching custom_id or id if it exists.

Return type:

Optional[Item]

await on_error(error, interaction)

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

This function is a coroutine.

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

Return type:

None

stop()

Stops listening to interaction events from the modal.

Return type:

None

property title: str

The title of the modal.

await wait()

Waits for the modal to be submitted.

Return type:

bool

Attributes
Methods
class discord.ui.DesignerModal(*children, title, custom_id=None, timeout=None, store=True)[source]

Represents a UI modal compatible with all modal features.

This object must be inherited to create a UI within Discord.

Added in version 2.7.

Parameters:

  • children (Union[ModalItem]) – The initial items that are displayed in the modal..

  • title (str) – The title of the modal. Must be 45 characters or fewer.

  • custom_id (Optional[str]) – The ID of the modal 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.

  • store (Optional[bool]) – Whether this modal should be stored for callback listening. Setting it to False will ignore its callback and prevent item values from being refreshed. Defaults to True.

property children: list[ModalItem]

The child items attached to the modal.

add_item(item)[source]

Adds a component to the modal.

Parameters:

item (Union[ModalItem]) – The item to add to the modal

Return type:

Self

await callback(interaction)

This function is a coroutine.

The coroutine that is called when the modal is submitted. Should be overridden to handle the values submitted by the user.

Parameters:

interaction (Interaction) – The interaction that submitted the modal.

property custom_id: str

The ID of the modal that gets received during an interaction.

get_item(custom_id)

Gets an item from this structure. Roughly equal to utils.get(self.children, …). If an int is provided, the item will be retrieved by id, otherwise by custom_id. This method will also search nested items.

Parameters:

custom_id (Union[str, int]) – The id of the item to get

Returns:

The item with the matching custom_id or id if it exists.

Return type:

Optional[Item]

await on_error(error, interaction)

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

This function is a coroutine.

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

Return type:

None

remove_item(item)

Removes a component from the modal.

Parameters:

item (ModalItem) – The item to remove from the modal.

Return type:

Self

stop()

Stops listening to interaction events from the modal.

Return type:

None

property title: str

The title of the modal.

await wait()

Waits for the modal to be submitted.

Return type:

bool

Attributes
Methods
class discord.ui.Label(label, item=None, *, description=None, id=None)[source]

Represents a UI Label used in discord.ui.DesignerModal.

The items currently supported are as follows:

Added in version 2.7.

Parameters:

  • item (ModalItem) – The initial item attached to this label.

  • label (str) – The label text. Must be 45 characters or fewer.

  • description (Optional[str]) – The description for this label. Must be 100 characters or fewer.

  • id (Optional[int]) – The label’s ID.

item

The label’s attached item.

Type:

ViewItem

property modal: M | None

Gets the parent modal associated with this item. This is typically set automatically when the item is added to a modal.

Returns:

The parent modal of this item, or None if the item is not attached to any modal.

Return type:

Optional[BaseModal]

set_item(item)[source]

Set this label’s item.

Parameters:

item (Union[ModalItem]) – The item to set.

Raises:

TypeError – A ModalItem was not passed.

Return type:

Self

get_item(id)[source]

Get the item from this label if it matches the provided id. If an int is provided, the item will match by id, otherwise by custom_id.

Parameters:

id (Union[str, int]) – The id or custom_id of the item to match.

Returns:

The item if its id or custom_id matches.

Return type:

Optional[ModalItem]

set_input_text(*, style=('short', 1), custom_id=None, placeholder=None, min_length=None, max_length=None, required=True, value=None, id=None)[source]

Set this label’s item to an input text.

To set a pre-existing InputText, use the set_item() method, instead.

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.

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

  • id (Optional[int]) – The button’s ID.

Return type:

Self

set_select(select_type=('string_select', 3), *, custom_id=None, placeholder=None, min_values=1, max_values=1, options=None, channel_types=None, required=True, id=None, default_values=Ellipsis)[source]

Set this label’s item to a select menu.

Parameters:
Return type:

Self

set_file_upload(*, custom_id=None, min_values=None, max_values=None, required=True, id=None)[source]

Set this label’s item to a file upload.

To set a pre-existing FileUpload, use the set_item() method, instead.

Parameters:

  • custom_id (Optional[str]) – The ID of the input text field that gets received during an interaction.

  • min_values (Optional[int]) – The minimum number of files that must be uploaded. Defaults to 0 and must be between 0 and 10, inclusive.

  • max_values (Optional[int]) – The maximum number of files that can be uploaded. Must be between 1 and 10, inclusive.

  • required (Optional[bool]) – Whether the file upload field is required or not. Defaults to True.

  • id (Optional[int]) – The file upload field’s ID.

Return type:

Self

property label: str

The label text. Must be 45 characters or fewer.

property description: str | None

The description for this label. Must be 100 characters or fewer.

property id: int | None

Gets this item’s ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item’s parent is sent.

Returns:

The ID of this item, or None if the user didn’t set one.

Return type:

Optional[int]

Attributes
class discord.ui.InputText(*, style=('short', 1), custom_id=None, label=None, placeholder=None, min_length=None, max_length=None, required=True, value=None, row=None, id=None)[source]

Represents a UI text input field.

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

  • id (int | None)

property style: InputTextStyle

The style of the input text field.

property custom_id: str

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

property label: str

The label of the input text field.

property placeholder: str | None

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

property min_length: int | None

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

property max_length: int | None

The maximum number of characters that can be entered.

property required: bool | None

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

property id: int | None

Gets this item’s ID.

This can be set by the user when constructing an Item. If not, Discord will automatically provide one when the item’s parent is sent.

Returns:

The ID of this item, or None if the user didn’t set one.

Return type:

Optional[int]

property modal: M | None

Gets the parent modal associated with this item. This is typically set automatically when the item is added to a modal.

Returns:

The parent modal of this item, or None if the item is not attached to any modal.

Return type:

Optional[BaseModal]

property value: str | None

The value entered in the text field.

Attributes
class discord.ui.FileUpload(*, custom_id=None, min_values=None, max_values=None, required=True, id=None)[source]

Represents a UI File Upload component.

Added in version 2.7.

Parameters:

  • custom_id (Optional[str]) – The ID of the input text field that gets received during an interaction.

  • min_values (Optional[int]) – The minimum number of files that must be uploaded. Defaults to 0 and must be between 0 and 10, inclusive.

  • max_values (Optional[int]) – The maximum number of files that can be uploaded. Must be between 1 and 10, inclusive.

  • required (Optional[bool]) – Whether the file upload field is required or not. Defaults to True.

  • id (Optional[int]) – The file upload field’s ID.

property id: int | None

The ID of this component. If not provided by the user, it is set sequentially by Discord.

property custom_id: str

The custom id that gets received during an interaction.

property min_values: int | None

The minimum number of files that must be uploaded. Defaults to 0.

property max_values: int | None

The maximum number of files that can be uploaded.

property required: bool

Whether the input file upload is required or not. Defaults to True.

property modal: M | None

Gets the parent modal associated with this item. This is typically set automatically when the item is added to a modal.

Returns:

The parent modal of this item, or None if the item is not attached to any modal.

Return type:

Optional[BaseModal]

property values: list[Attachment] | None

The files that were uploaded to the field.