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

  • id (int | None)

Return type:

Callable[[Callable[[Any, TypeVar(I, bound= Item), Interaction], Coroutine[Any, Any, Any]]], Callable[[Any, TypeVar(I, bound= Item), Interaction], Coroutine[Any, Any, Any]]]

@discord.ui.select(select_type=('string_select', 3), *, placeholder=None, custom_id=None, min_values=1, max_values=1, options=Undefined.MISSING, channel_types=Undefined.MISSING, disabled=False, row=None, id=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.

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

Return type:

Callable[[Callable[[Any, TypeVar(I, bound= Item), Interaction], Coroutine[Any, Any, Any]]], Callable[[Any, TypeVar(I, bound= Item), Interaction], Coroutine[Any, Any, Any]]]

@discord.ui.string_select(*, placeholder=None, custom_id=None, min_values=1, max_values=1, options=Undefined.MISSING, 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, TypeVar(I, bound= Item), Interaction], Coroutine[Any, Any, Any]]], Callable[[Any, TypeVar(I, bound= Item), Interaction], Coroutine[Any, Any, Any]]]

@discord.ui.user_select(*, placeholder=None, custom_id=None, min_values=1, max_values=1, disabled=False, row=None, id=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, TypeVar(I, bound= Item), Interaction], Coroutine[Any, Any, Any]]], Callable[[Any, TypeVar(I, bound= Item), Interaction], Coroutine[Any, Any, Any]]]

@discord.ui.role_select(*, placeholder=None, custom_id=None, min_values=1, max_values=1, disabled=False, row=None, id=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, TypeVar(I, bound= Item), Interaction], Coroutine[Any, Any, Any]]], Callable[[Any, TypeVar(I, bound= Item), Interaction], Coroutine[Any, Any, Any]]]

@discord.ui.mentionable_select(*, placeholder=None, custom_id=None, min_values=1, max_values=1, disabled=False, row=None, id=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, TypeVar(I, bound= Item), Interaction], Coroutine[Any, Any, Any]]], Callable[[Any, TypeVar(I, bound= Item), Interaction], Coroutine[Any, Any, Any]]]

@discord.ui.channel_select(*, placeholder=None, custom_id=None, min_values=1, max_values=1, disabled=False, channel_types=Undefined.MISSING, row=None, id=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, TypeVar(I, bound= Item), Interaction], Coroutine[Any, Any, Any]]], Callable[[Any, TypeVar(I, bound= Item), Interaction], Coroutine[Any, Any, Any]]]

Objects

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

Added 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. Defaults to 180.0. 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]

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.

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 (40) 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. If an int or str is passed, the item will be removed by Item id or custom_id respectively.

Parameters:

item (Union[Item, int, str]) – The item, item id, or item custom_id 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]

Gets an item from the view. Roughly equal to utils.find(lambda i: i.custom_id == custom_id, 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 (str) – The custom_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)[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

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

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[Item]]) – A list of items in self.children to not disable from the view.

Return type:

None

enable_all_items(*, exclusions=None)[source]

Enables all buttons and select menus in the view.

Parameters:

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

Return type:

None

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.Item[source]

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

The following are the original items:

And the following are new items under the “Components V2” specification:

Added in version 2.0.

Changed in version 2.7: Added V2 Components.

property row

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 39 (inclusive), or None to indicate that no specific row is set.

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, 39].

property width

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. Defaults to 1.

Return type:

int

property id

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 View is sent.

Returns:

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

Return type:

Optional[int]

property view

Gets the parent view associated with this item.

The view refers to the container 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[View]

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.

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 with V2 components or with more than 25 items in your view.

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

property row

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 39 (inclusive), or None to indicate that no specific row is set.

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, 39].

property style

The style of the button.

property custom_id

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

If this button is for a URL, it does not have a custom ID.

property url

The URL this button sends you to.

property disabled

Whether the button is disabled or not.

property label

The label of the button, if available.

property emoji

The emoji of the button, if available.

property sku_id

The ID of the SKU this button refers to.

await callback(interaction)

This function is a coroutine.

The callback associated with this UI item.

This can be overridden by subclasses.

Parameters:

interaction (Interaction) – The interaction that triggered this UI item.

property id

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 View is sent.

Returns:

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

Return type:

Optional[int]

property view

Gets the parent view associated with this item.

The view refers to the container 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[View]

property width

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. Defaults to 1.

Return type:

int

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

Parameters:
property row

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 39 (inclusive), or None to indicate that no specific row is set.

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, 39].

property custom_id

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

property placeholder

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

property min_values

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

property max_values

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

property disabled

Whether the select is disabled or not.

property channel_types

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

property options

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

add_option(*, label, value=Undefined.MISSING, 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[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

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

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 View is sent.

Returns:

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

Return type:

Optional[int]

property view

Gets the parent view associated with this item.

The view refers to the container 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[View]

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 (Item) – 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[Item]) – 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.

add_item(item)[source]

Adds an item to the section.

Parameters:

item (Item) – 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[Item, 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[Item]

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 (Item) – The item to set as accessory. Currently only supports Button and Thumbnail.

Raises:

TypeError – An Item 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

property view

Gets the parent view associated with this item.

The view refers to the container 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[View]

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

property width

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. Defaults to 1.

Return type:

int

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[Item]]) – 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[Item]]) – A list of items in self.items to not enable from the view.

Return type:

Self

property id

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 View is sent.

Returns:

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

Return type:

Optional[int]

property row

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 39 (inclusive), or None to indicate that no specific row is set.

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, 39].

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

The text display’s content.

property width

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. Defaults to 1.

Return type:

int

copy_text()[source]

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

Return type:

str

property id

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 View is sent.

Returns:

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

Return type:

Optional[int]

property row

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 39 (inclusive), or None to indicate that no specific row is set.

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, 39].

property view

Gets the parent view associated with this item.

The view refers to the container 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[View]

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 width

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. Defaults to 1.

Return type:

int

property url

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

property description

The thumbnail’s description, up to 1024 characters.

property spoiler

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

property id

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 View is sent.

Returns:

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

Return type:

Optional[int]

property row

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 39 (inclusive), or None to indicate that no specific row is set.

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, 39].

property view

Gets the parent view associated with this item.

The view refers to the container 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[View]

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.

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:

None

property view

Gets the parent view associated with this item.

The view refers to the container 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[View]

property width

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. Defaults to 1.

Return type:

int

property id

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 View is sent.

Returns:

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

Return type:

Optional[int]

property row

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 39 (inclusive), or None to indicate that no specific row is set.

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, 39].

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 width

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. Defaults to 1.

Return type:

int

property url

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

property spoiler

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

property name

The name of this file, if provided by Discord.

property size

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

property id

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 View is sent.

Returns:

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

Return type:

Optional[int]

property row

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 39 (inclusive), or None to indicate that no specific row is set.

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, 39].

property view

Gets the parent view associated with this item.

The view refers to the container 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[View]

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

Whether the separator is a divider. Defaults to True.

property spacing

The spacing size of the separator. Defaults to small.

property width

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. Defaults to 1.

Return type:

int

property id

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 View is sent.

Returns:

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

Return type:

Optional[int]

property row

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 39 (inclusive), or None to indicate that no specific row is set.

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, 39].

property view

Gets the parent view associated with this item.

The view refers to the container 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[View]

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 (Item) – 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.

  • color (int | Colour | None)

add_item(item)[source]

Adds an item to the container.

Parameters:

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

Raises:

TypeError – An Item 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[Item, 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[Item]

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 (Item) – The items contained in this section, up to 3. Currently only supports TextDisplay.

  • accessory (Optional[Item]) – 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

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

property view

Gets the parent view associated with this item.

The view refers to the container 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[View]

property width

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. Defaults to 1.

Return type:

int

disable_all_items(*, exclusions=None)[source]

Disables all buttons and select menus in the container.

Parameters:

exclusions (Optional[List[Item]]) – 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[Item]]) – A list of items in self.items to not enable from the view.

Return type:

Self

property id

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 View is sent.

Returns:

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

Return type:

Optional[int]

property row

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 39 (inclusive), or None to indicate that no specific row is set.

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, 39].

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.

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

property children

The child components associated with the modal dialog.

property custom_id

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

await callback(interaction)[source]

This function is a coroutine.

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

Parameters:

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

add_item(item)[source]

Adds an InputText component to the modal dialog.

Parameters:

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

Return type:

Self

remove_item(item)[source]

Removes an InputText component from the modal dialog.

Parameters:

item (InputText) – The item to remove from the modal dialog.

Return type:

Self

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

Attributes
class discord.ui.InputText(*, style=('short', 1), custom_id=None, label, 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 id

The input text’s ID. If not provided by the user, it is set sequentially by Discord.

property style

The style of the input text field.

property custom_id

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

property label

The label of the input text field.

property placeholder

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

property min_length

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

property max_length

The maximum number of characters that can be entered.

property required

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

property value

The value entered in the text field.