Bot UI Kit

This section documents everything related to the Discord Bot UI Kit - a group of helper functions and classes that aid in making component-based UIs.

Classes

View

Attributes
Methods
class disnake.ui.View(*, timeout=180.0)[source]

Represents a UI view.

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

Alternatively, components can be handled with disnake.ui.ActionRows and event listeners for a more low-level approach. Relevant events are disnake.on_button_click(), disnake.on_dropdown(), and the more generic disnake.on_message_interaction().

New in version 2.0.

Parameters:

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

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

Parameters:

  • message (disnake.Message) – The message with components to convert into a view.

  • timeout (Optional[float]) – The timeout of the converted view.

Returns:

The converted view. This always returns a View and not one of its subclasses.

Return type:

View

add_item(item)[source]

Adds an item to the view.

This function returns the class instance to allow for fluent-style chaining.

Parameters:

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

Raises:

  • TypeError – An Item was not passed.

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

remove_item(item)[source]

Removes an item from the view.

This function returns the class instance to allow for fluent-style chaining.

Parameters:

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

clear_items()[source]

Removes all items from the view.

This function returns the class instance to allow for fluent-style chaining.

await interaction_check(interaction)[source]

This function is a coroutine.

A callback that is called when an interaction happens within the view that checks whether the view should process item callbacks for the interaction.

This is useful to override if, for example, you want to ensure that the interaction author is a given user.

The default implementation of this returns True.

Note

If an exception occurs within the body then the check is considered a failure and on_error() is called.

Parameters:

interaction (MessageInteraction) – The interaction that occurred.

Returns:

Whether the view children’s callbacks should be called.

Return type:

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.

await on_error(error, item, interaction)[source]

This function is a coroutine.

A callback that is called when an item’s callback or interaction_check() fails with an error.

The default implementation prints the traceback to stderr.

Parameters:

  • error (Exception) – The exception that was raised.

  • item (Item) – The item that failed the dispatch.

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

stop()[source]

Stops listening to interaction events from this view.

This operation cannot be undone.

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 only has components with a set custom_id (or non-interactive components such as link or premium buttons), and a timeout set to None.

Return type:

bool

await wait()[source]

Waits until the view has finished interacting.

A view is considered finished when stop() is called or it times out.

Returns:

If True, then the view timed out. If False then the view finished normally.

Return type:

bool

ActionRow

Attributes
Methods
class disnake.ui.ActionRow(*components)[source]

Represents a UI action row. Useful for lower level component manipulation.

x[i]

Returns the component at position i. Also supports slices.

New in version 2.6.

len(x)

Returns the number of components in this row.

New in version 2.6.

iter(x)

Returns an iterator for the components in this row.

New in version 2.6.

To handle interactions created by components sent in action rows or entirely independently, event listeners must be used. For buttons and selects, the related events are disnake.on_button_click() and disnake.on_dropdown(), respectively. Alternatively, disnake.on_message_interaction() can be used for either. For modals, the related event is disnake.on_modal_submit().

New in version 2.4.

Changed in version 2.6: Requires and provides stricter typing for contained components.

Parameters:

*components (WrappedComponent) –

The components of this action row.

Changed in version 2.6: Components can now be either valid in the context of a message, or in the context of a modal. Combining components from both contexts is not supported.

property children[source]

Sequence[WrappedComponent]: A read-only copy of the UI components stored in this action row. To add/remove components to/from the action row, use its methods to directly modify it.

Changed in version 2.6: Returns an immutable sequence instead of a list.

append_item(item)[source]

Append a component to the action row. The component’s type must match that of the action row.

This function returns the class instance to allow for fluent-style chaining.

Parameters:

item (WrappedComponent) – The component to append to the action row.

Raises:

ValueError – The width of the action row exceeds 5.

insert_item(index, item)[source]

Insert a component to the action row at a given index. The component’s type must match that of the action row.

This function returns the class instance to allow for fluent-style chaining.

New in version 2.6.

Parameters:

  • index (int) – The index at which to insert the component into the action row.

  • item (WrappedComponent) – The component to insert into the action row.

Raises:

ValueError – The width of the action row exceeds 5.

add_button(index=None, *, style=ButtonStyle.secondary, label=None, disabled=False, custom_id=None, url=None, emoji=None, sku_id=None)[source]

Add a button to the action row. Can only be used if the action row holds message components.

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

This function returns the class instance to allow for fluent-style chaining.

Changed in version 2.6: Now allows for inserting at a given index. The default behaviour of appending is preserved.

Parameters:

  • index (int) – The index at which to insert the button into the action row. If not provided, this method defaults to appending the button to the action row.

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

  • custom_id (Optional[str]) – The ID of the button that gets received during an interaction. If this button is for a URL, it does not have a custom ID.

  • url (Optional[str]) – The URL this button sends you to.

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

  • label (Optional[str]) – The label of the button, if any.

  • emoji (Optional[Union[PartialEmoji, Emoji, str]]) – The emoji of the button, if available.

  • sku_id (Optional[int]) –

    The ID of a purchasable SKU, for premium buttons. Premium buttons additionally cannot have a label, url, or emoji.

    New in version 2.11.

Raises:

ValueError – The width of the action row exceeds 5.

add_string_select(*, custom_id=..., placeholder=None, min_values=1, max_values=1, options=..., disabled=False)[source]

Add a string select menu to the action row. Can only be used if the action row holds message components.

To append a pre-existing StringSelect use the append_item() method instead.

This function returns the class instance to allow for fluent-style chaining.

Changed in version 2.7: Renamed from add_select to add_string_select.

Parameters:

  • custom_id (str) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is selected, if any.

  • min_values (int) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • max_values (int) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • options (Union[List[disnake.SelectOption], List[str], Dict[str, str]]) – A list of options that can be selected in this menu. Use explicit SelectOptions for fine-grained control over the options. Alternatively, a list of strings will be treated as a list of labels, and a dict will be treated as a mapping of labels to values.

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

Raises:

ValueError – The width of the action row exceeds 5.

add_user_select(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None)[source]

Add a user select menu to the action row. Can only be used if the action row holds message components.

To append a pre-existing UserSelect use the append_item() method instead.

This function returns the class instance to allow for fluent-style chaining.

New in version 2.7.

Parameters:

  • custom_id (str) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is selected, if any.

  • min_values (int) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • max_values (int) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

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

  • default_values (Optional[Sequence[Union[User, Member, SelectDefaultValue, Object]]]) –

    The list of values (users/members) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values.

    New in version 2.10.

Raises:

ValueError – The width of the action row exceeds 5.

add_role_select(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None)[source]

Add a role select menu to the action row. Can only be used if the action row holds message components.

To append a pre-existing RoleSelect use the append_item() method instead.

This function returns the class instance to allow for fluent-style chaining.

New in version 2.7.

Parameters:

  • custom_id (str) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is selected, if any.

  • min_values (int) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • max_values (int) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

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

  • default_values (Optional[Sequence[Union[Role, SelectDefaultValue, Object]]]) –

    The list of values (roles) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values.

    New in version 2.10.

Raises:

ValueError – The width of the action row exceeds 5.

add_mentionable_select(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None)[source]

Add a mentionable (user/member/role) select menu to the action row. Can only be used if the action row holds message components.

To append a pre-existing MentionableSelect use the append_item() method instead.

This function returns the class instance to allow for fluent-style chaining.

New in version 2.7.

Parameters:

  • custom_id (str) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is selected, if any.

  • min_values (int) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • max_values (int) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

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

  • default_values (Optional[Sequence[Union[User, Member, Role, SelectDefaultValue]]]) –

    The list of values (users/roles) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values.

    Note that unlike other select menu types, this does not support Objects due to ambiguities.

    New in version 2.10.

Raises:

ValueError – The width of the action row exceeds 5.

add_channel_select(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, channel_types=None, default_values=None)[source]

Add a channel select menu to the action row. Can only be used if the action row holds message components.

To append a pre-existing ChannelSelect use the append_item() method instead.

This function returns the class instance to allow for fluent-style chaining.

New in version 2.7.

Parameters:

  • custom_id (str) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is selected, if any.

  • min_values (int) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • max_values (int) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

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

  • channel_types (Optional[List[ChannelType]]) – The list of channel types that can be selected in this select menu. Defaults to all types (i.e. None).

  • default_values (Optional[Sequence[Union[abc.GuildChannel, Thread, abc.PrivateChannel, PartialMessageable, SelectDefaultValue, Object]]]) –

    The list of values (channels) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values.

    New in version 2.10.

Raises:

ValueError – The width of the action row exceeds 5.

add_text_input(*, label, custom_id, style=TextInputStyle.short, placeholder=None, value=None, required=True, min_length=None, max_length=None)[source]

Add a text input to the action row. Can only be used if the action row holds modal components.

To append a pre-existing TextInput use the append_item() method instead.

This function returns the class instance to allow for fluent-style chaining.

New in version 2.4.

Parameters:

  • style (TextInputStyle) – The style of the text input.

  • label (str) – The label of the text input.

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

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is entered.

  • value (Optional[str]) – The pre-filled value of the text input.

  • required (bool) – Whether the text input is required. Defaults to True.

  • min_length (Optional[int]) – The minimum length of the text input.

  • max_length (Optional[int]) – The maximum length of the text input.

Raises:

ValueError – The width of the action row exceeds 5.

clear_items()[source]

Remove all components from the action row.

This function returns the class instance to allow for fluent-style chaining.

New in version 2.6.

remove_item(item)[source]

Remove a component from the action row.

This function returns the class instance to allow for fluent-style chaining.

New in version 2.6.

Parameters:

item (WrappedComponent) – The component to remove from the action row.

Raises:

ValueError – The component could not be found on the action row.

pop(index)[source]

Pop the component at the provided index from the action row.

New in version 2.6.

Parameters:

index (int) – The index at which to pop the component.

Raises:

IndexError – There is no component at the provided index.

classmethod with_modal_components()[source]

Create an empty action row meant to store components compatible with disnake.ui.Modal. Saves the need to import type specifiers to typehint empty action rows.

New in version 2.6.

Returns:

The newly created empty action row, intended for modal components.

Return type:

ActionRow

classmethod with_message_components()[source]

Create an empty action row meant to store components compatible with disnake.Message. Saves the need to import type specifiers to typehint empty action rows.

New in version 2.6.

Returns:

The newly created empty action row, intended for message components.

Return type:

ActionRow

classmethod rows_from_message(message, *, strict=True)[source]

Create a list of up to 5 action rows from the components on an existing message.

This will abide by existing component format on the message, including component ordering and rows. Components will be transformed to UI kit components, such that they can be easily modified and re-sent as action rows.

New in version 2.6.

Parameters:

  • message (disnake.Message) – The message from which to extract the components.

  • strict (bool) – Whether or not to raise an exception if an unknown component type is encountered.

Raises:

TypeError – Strict-mode is enabled and an unknown component type is encountered.

Returns:

The action rows parsed from the components on the message.

Return type:

List[ActionRow]

staticmethod for ... in walk_components(action_rows)[source]

Iterate over the components in a sequence of action rows, yielding each individual component together with the action row of which it is a child.

New in version 2.6.

Parameters:

action_rows (Sequence[ActionRow]) – The sequence of action rows over which to iterate.

Yields:

Tuple[ActionRow, WrappedComponent] – A tuple containing an action row and a component of that action row.

Item

Attributes
Methods
class disnake.ui.Item[source]

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

This class adds more functionality on top of the WrappedComponent base class. This functionality mostly relates to disnake.ui.View.

The current UI items supported are:

New in version 2.0.

property view[source]

The underlying view for this item.

Type:

Optional[View]

await callback(interaction, /)[source]

This function is a coroutine.

The callback associated with this UI item.

This can be overriden by subclasses.

Parameters:

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

WrappedComponent

class disnake.ui.WrappedComponent[source]

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

The following classes implement this ABC:

New in version 2.4.

Button

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

Represents a UI button.

New in version 2.0.

Parameters:

  • style (disnake.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 or an SKU, it does not have a custom ID.

  • url (Optional[str]) – The URL this button sends you to.

  • disabled (bool) – Whether the button is disabled.

  • label (Optional[str]) – The label of the button, if any.

  • emoji (Optional[Union[PartialEmoji, Emoji, str]]) – The emoji of the button, if available.

  • sku_id (Optional[int]) –

    The ID of a purchasable SKU, for premium buttons. Premium buttons additionally cannot have a label, url, or emoji.

    New in version 2.11.

  • row (Optional[int]) – The relative row this button belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults to None, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).

property style[source]

The style of the button.

Type:

disnake.ButtonStyle

property custom_id[source]

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

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

Type:

Optional[str]

property url[source]

The URL this button sends you to.

Type:

Optional[str]

property disabled[source]

Whether the button is disabled.

Type:

bool

await callback(interaction, /)[source]

This function is a coroutine.

The callback associated with this UI item.

This can be overriden by subclasses.

Parameters:

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

property view[source]

The underlying view for this item.

Type:

Optional[View]

property label[source]

The label of the button, if available.

Type:

Optional[str]

property emoji[source]

The emoji of the button, if available.

Type:

Optional[PartialEmoji]

property sku_id[source]

The ID of a purchasable SKU, for premium buttons.

New in version 2.11.

Type:

Optional[int]

BaseSelect

Attributes
Methods
class disnake.ui.BaseSelect(underlying_type, component_type, *, custom_id, placeholder, min_values, max_values, disabled, default_values, row)[source]

Represents an abstract UI select menu.

This is usually represented as a drop down menu.

This isn’t meant to be used directly, instead use one of the concrete select menu types:

New in version 2.7.

property custom_id[source]

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

Type:

str

property placeholder[source]

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

Type:

Optional[str]

property min_values[source]

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

Type:

int

property max_values[source]

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

Type:

int

property disabled[source]

Whether the select menu is disabled.

Type:

bool

property default_values[source]

The list of values that are selected by default. Only available for auto-populated select menus.

Type:

List[SelectDefaultValue]

await callback(interaction, /)[source]

This function is a coroutine.

The callback associated with this UI item.

This can be overriden by subclasses.

Parameters:

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

property view[source]

The underlying view for this item.

Type:

Optional[View]

is_dispatchable()[source]

Whether the select menu is dispatchable. This will always return True.

Return type:

bool

StringSelect

Attributes
Methods
class disnake.ui.StringSelect(*, custom_id=..., placeholder=None, min_values=1, max_values=1, options=..., disabled=False, row=None)[source]

Represents a UI string select menu.

This is usually represented as a drop down menu.

In order to get the selected items that the user has chosen, use values.

New in version 2.0.

Changed in version 2.7: Renamed from Select to StringSelect.

Parameters:

  • custom_id (str) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is selected, if any.

  • min_values (int) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • max_values (int) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • options (Union[List[disnake.SelectOption], List[str], Dict[str, str]]) –

    A list of options that can be selected in this menu. Use explicit SelectOptions for fine-grained control over the options. Alternatively, a list of strings will be treated as a list of labels, and a dict will be treated as a mapping of labels to values.

    Changed in version 2.5: Now also accepts a list of str or a dict of str to str, which are then appropriately parsed as SelectOption labels and values.

  • disabled (bool) – Whether the select is disabled.

  • row (Optional[int]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults to None, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).

values[source]

A list of values that have been selected by the user.

Type:

List[str]

property options[source]

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

Type:

List[disnake.SelectOption]

add_option(*, label, value=..., description=None, emoji=None, default=False)[source]

Adds an option to the select menu.

To append a pre-existing SelectOption use the append_option() method instead.

Parameters:

  • label (str) – The label of the option. This is displayed to users. Can only be up to 100 characters.

  • value (str) – The value of the option. This is not displayed to users. If not given, defaults to the label. Can only be up to 100 characters.

  • description (Optional[str]) – An additional description of the option, if any. Can only be up to 100 characters.

  • emoji (Optional[Union[str, Emoji, PartialEmoji]]) – The emoji of the option, if available. This can either be a string representing the custom or unicode emoji or an instance of PartialEmoji or Emoji.

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

Raises:

ValueError – The number of options exceeds 25.

append_option(option)[source]

Appends an option to the select menu.

Parameters:

option (disnake.SelectOption) – The option to append to the select menu.

Raises:

ValueError – The number of options exceeds 25.

await callback(interaction, /)[source]

This function is a coroutine.

The callback associated with this UI item.

This can be overriden by subclasses.

Parameters:

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

property custom_id[source]

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

Type:

str

property disabled[source]

Whether the select menu is disabled.

Type:

bool

is_dispatchable()[source]

Whether the select menu is dispatchable. This will always return True.

Return type:

bool

property max_values[source]

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

Type:

int

property min_values[source]

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

Type:

int

property placeholder[source]

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

Type:

Optional[str]

property view[source]

The underlying view for this item.

Type:

Optional[View]

ChannelSelect

Attributes
Methods
class disnake.ui.ChannelSelect(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, channel_types=None, default_values=None, row=None)[source]

Represents a UI channel select menu.

This is usually represented as a drop down menu.

In order to get the selected items that the user has chosen, use values.

New in version 2.7.

Parameters:

  • custom_id (str) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is selected, if any.

  • min_values (int) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • max_values (int) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • disabled (bool) – Whether the select is disabled.

  • channel_types (Optional[List[ChannelType]]) – The list of channel types that can be selected in this select menu. Defaults to all types (i.e. None).

  • default_values (Optional[Sequence[Union[abc.GuildChannel, Thread, abc.PrivateChannel, PartialMessageable, SelectDefaultValue, Object]]]) –

    The list of values (channels) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values.

    New in version 2.10.

  • row (Optional[int]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults to None, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).

values[source]

A list of channels that have been selected by the user.

Type:

List[Union[abc.GuildChannel, Thread, abc.PrivateChannel, PartialMessageable]]

await callback(interaction, /)[source]

This function is a coroutine.

The callback associated with this UI item.

This can be overriden by subclasses.

Parameters:

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

property channel_types[source]

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

Type:

Optional[List[disnake.ChannelType]]

property custom_id[source]

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

Type:

str

property default_values[source]

The list of values that are selected by default. Only available for auto-populated select menus.

Type:

List[SelectDefaultValue]

property disabled[source]

Whether the select menu is disabled.

Type:

bool

is_dispatchable()[source]

Whether the select menu is dispatchable. This will always return True.

Return type:

bool

property max_values[source]

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

Type:

int

property min_values[source]

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

Type:

int

property placeholder[source]

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

Type:

Optional[str]

property view[source]

The underlying view for this item.

Type:

Optional[View]

MentionableSelect

Attributes
Methods
class disnake.ui.MentionableSelect(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None, row=None)[source]

Represents a UI mentionable (user/member/role) select menu.

This is usually represented as a drop down menu.

In order to get the selected items that the user has chosen, use values.

New in version 2.7.

Parameters:

  • custom_id (str) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is selected, if any.

  • min_values (int) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • max_values (int) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • disabled (bool) – Whether the select is disabled.

  • default_values (Optional[Sequence[Union[User, Member, Role, SelectDefaultValue]]]) –

    The list of values (users/roles) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values.

    Note that unlike other select menu types, this does not support Objects due to ambiguities.

    New in version 2.10.

  • row (Optional[int]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults to None, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).

values[source]

A list of users, members and/or roles that have been selected by the user.

Type:

List[Union[User, Member, Role]]

await callback(interaction, /)[source]

This function is a coroutine.

The callback associated with this UI item.

This can be overriden by subclasses.

Parameters:

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

property custom_id[source]

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

Type:

str

property default_values[source]

The list of values that are selected by default. Only available for auto-populated select menus.

Type:

List[SelectDefaultValue]

property disabled[source]

Whether the select menu is disabled.

Type:

bool

is_dispatchable()[source]

Whether the select menu is dispatchable. This will always return True.

Return type:

bool

property max_values[source]

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

Type:

int

property min_values[source]

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

Type:

int

property placeholder[source]

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

Type:

Optional[str]

property view[source]

The underlying view for this item.

Type:

Optional[View]

RoleSelect

Attributes
Methods
class disnake.ui.RoleSelect(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None, row=None)[source]

Represents a UI role select menu.

This is usually represented as a drop down menu.

In order to get the selected items that the user has chosen, use values.

New in version 2.7.

Parameters:

  • custom_id (str) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is selected, if any.

  • min_values (int) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • max_values (int) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • disabled (bool) – Whether the select is disabled.

  • default_values (Optional[Sequence[Union[Role, SelectDefaultValue, Object]]]) –

    The list of values (roles) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values.

    New in version 2.10.

  • row (Optional[int]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults to None, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).

values[source]

A list of roles that have been selected by the user.

Type:

List[Role]

await callback(interaction, /)[source]

This function is a coroutine.

The callback associated with this UI item.

This can be overriden by subclasses.

Parameters:

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

property custom_id[source]

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

Type:

str

property default_values[source]

The list of values that are selected by default. Only available for auto-populated select menus.

Type:

List[SelectDefaultValue]

property disabled[source]

Whether the select menu is disabled.

Type:

bool

is_dispatchable()[source]

Whether the select menu is dispatchable. This will always return True.

Return type:

bool

property max_values[source]

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

Type:

int

property min_values[source]

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

Type:

int

property placeholder[source]

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

Type:

Optional[str]

property view[source]

The underlying view for this item.

Type:

Optional[View]

UserSelect

Attributes
Methods
class disnake.ui.UserSelect(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None, row=None)[source]

Represents a UI user select menu.

This is usually represented as a drop down menu.

In order to get the selected items that the user has chosen, use values.

New in version 2.7.

Parameters:

  • custom_id (str) – The ID of the select menu that gets received during an interaction. If not given then one is generated for you.

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is selected, if any.

  • min_values (int) – The minimum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • max_values (int) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • disabled (bool) – Whether the select is disabled.

  • default_values (Optional[Sequence[Union[User, Member, SelectDefaultValue, Object]]]) –

    The list of values (users/members) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values.

    New in version 2.10.

  • row (Optional[int]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults to None, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).

values[source]

A list of users/members that have been selected by the user.

Type:

List[User, Member]

await callback(interaction, /)[source]

This function is a coroutine.

The callback associated with this UI item.

This can be overriden by subclasses.

Parameters:

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

property custom_id[source]

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

Type:

str

property default_values[source]

The list of values that are selected by default. Only available for auto-populated select menus.

Type:

List[SelectDefaultValue]

property disabled[source]

Whether the select menu is disabled.

Type:

bool

is_dispatchable()[source]

Whether the select menu is dispatchable. This will always return True.

Return type:

bool

property max_values[source]

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

Type:

int

property min_values[source]

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

Type:

int

property placeholder[source]

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

Type:

Optional[str]

property view[source]

The underlying view for this item.

Type:

Optional[View]

TextInput

Attributes
class disnake.ui.TextInput(*, label, custom_id, style=TextInputStyle.short, placeholder=None, value=None, required=True, min_length=None, max_length=None)[source]

Represents a UI text input.

This can only be used in a Modal.

New in version 2.4.

Parameters:

  • label (str) – The label of the text input.

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

  • style (TextInputStyle) – The style of the text input.

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is entered.

  • value (Optional[str]) – The pre-filled value of the text input.

  • required (bool) – Whether the text input is required. Defaults to True.

  • min_length (Optional[int]) – The minimum length of the text input.

  • max_length (Optional[int]) – The maximum length of the text input.

property style[source]

The style of the text input.

Type:

TextInputStyle

property label[source]

The label of the text input.

Type:

str

property custom_id[source]

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

Type:

str

property placeholder[source]

The placeholder text that is shown if nothing is entered.

Type:

Optional[str]

property value[source]

The pre-filled text of the text input.

Type:

Optional[str]

property required[source]

Whether the text input is required.

Type:

bool

property min_length[source]

The minimum length of the text input.

Type:

Optional[int]

property max_length[source]

The maximum length of the text input.

Type:

Optional[int]

Functions

@disnake.ui.button(cls=Button, *, custom_id=..., style=ButtonStyle.secondary, label=None, disabled=False, url=None, emoji=None, row=None)[source]

A decorator that attaches a button to a component.

The function being decorated should have three parameters, self representing the disnake.ui.View, the disnake.ui.Button that was interacted with, and the disnake.MessageInteraction.

Note

Link/Premium buttons cannot be created with this function, since these buttons do not have a callback associated with them. Consider creating a Button manually instead, and adding it using View.add_item().

Parameters:

  • cls (Callable[…, Button]) –

    A callable (may be a Button subclass) to create a new instance of this component. If provided, the other parameters described below do not apply. Instead, this decorator will accept the same keywords as the passed callable/class does.

    New in version 2.6.

  • label (Optional[str]) – The label of the button, if any.

  • custom_id (Optional[str]) – The ID of the button that gets received during an interaction. It is recommended not to set this parameter to prevent conflicts.

  • style (ButtonStyle) – The style of the button. Defaults to ButtonStyle.grey.

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

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

  • row (Optional[int]) – The relative row this button belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults to None, which is automatic ordering. The row number must be between 0 and 4 (i.e. zero indexed).

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

A decorator that attaches a string select menu to a component.

The function being decorated should have three parameters, self representing the disnake.ui.View, the disnake.ui.StringSelect that was interacted with, and the disnake.MessageInteraction.

In order to get the selected items that the user has chosen within the callback use StringSelect.values.

Changed in version 2.7: Renamed from select to string_select.

Parameters:

  • cls (Callable[…, StringSelect]) –

    A callable (may be a StringSelect subclass) to create a new instance of this component. If provided, the other parameters described below do not apply. Instead, this decorator will accept the same keywords as the passed callable/class does.

    New in version 2.6.

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is selected, if any.

  • custom_id (str) – The ID of the select menu that gets received during an interaction. It is recommended not to set this parameter to prevent conflicts.

  • row (Optional[int]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults 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 1 and 25.

  • max_values (int) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

  • options (Union[List[disnake.SelectOption], List[str], Dict[str, str]]) –

    A list of options that can be selected in this menu. Use explicit SelectOptions for fine-grained control over the options. Alternatively, a list of strings will be treated as a list of labels, and a dict will be treated as a mapping of labels to values.

    Changed in version 2.5: Now also accepts a list of str or a dict of str to str, which are then appropriately parsed as SelectOption labels and values.

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

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

A decorator that attaches a channel select menu to a component.

The function being decorated should have three parameters, self representing the disnake.ui.View, the disnake.ui.ChannelSelect that was interacted with, and the disnake.MessageInteraction.

In order to get the selected items that the user has chosen within the callback use ChannelSelect.values.

New in version 2.7.

Parameters:

  • cls (Callable[…, ChannelSelect]) – A callable (may be a ChannelSelect subclass) to create a new instance of this component. If provided, the other parameters described below do not apply. Instead, this decorator will accept the same keywords as the passed callable/class does.

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is selected, if any.

  • custom_id (str) – The ID of the select menu that gets received during an interaction. It is recommended not to set this parameter to prevent conflicts.

  • row (Optional[int]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults 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 1 and 25.

  • max_values (int) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

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

  • channel_types (Optional[List[ChannelType]]) – The list of channel types that can be selected in this select menu. Defaults to all types (i.e. None).

  • default_values (Optional[Sequence[Union[abc.GuildChannel, Thread, abc.PrivateChannel, PartialMessageable, SelectDefaultValue, Object]]]) –

    The list of values (channels) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values.

    New in version 2.10.

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

A decorator that attaches a mentionable (user/member/role) select menu to a component.

The function being decorated should have three parameters, self representing the disnake.ui.View, the disnake.ui.MentionableSelect that was interacted with, and the disnake.MessageInteraction.

In order to get the selected items that the user has chosen within the callback use MentionableSelect.values.

New in version 2.7.

Parameters:

  • cls (Callable[…, MentionableSelect]) – A callable (may be a MentionableSelect subclass) to create a new instance of this component. If provided, the other parameters described below do not apply. Instead, this decorator will accept the same keywords as the passed callable/class does.

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is selected, if any.

  • custom_id (str) – The ID of the select menu that gets received during an interaction. It is recommended not to set this parameter to prevent conflicts.

  • row (Optional[int]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults 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 1 and 25.

  • max_values (int) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

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

  • default_values (Optional[Sequence[Union[User, Member, Role, SelectDefaultValue]]]) –

    The list of values (users/roles) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values.

    Note that unlike other select menu types, this does not support Objects due to ambiguities.

    New in version 2.10.

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

A decorator that attaches a role select menu to a component.

The function being decorated should have three parameters, self representing the disnake.ui.View, the disnake.ui.RoleSelect that was interacted with, and the disnake.MessageInteraction.

In order to get the selected items that the user has chosen within the callback use RoleSelect.values.

New in version 2.7.

Parameters:

  • cls (Callable[…, RoleSelect]) – A callable (may be a RoleSelect subclass) to create a new instance of this component. If provided, the other parameters described below do not apply. Instead, this decorator will accept the same keywords as the passed callable/class does.

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is selected, if any.

  • custom_id (str) – The ID of the select menu that gets received during an interaction. It is recommended not to set this parameter to prevent conflicts.

  • row (Optional[int]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults 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 1 and 25.

  • max_values (int) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

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

  • default_values (Optional[Sequence[Union[Role, SelectDefaultValue, Object]]]) –

    The list of values (roles) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values.

    New in version 2.10.

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

A decorator that attaches a user select menu to a component.

The function being decorated should have three parameters, self representing the disnake.ui.View, the disnake.ui.UserSelect that was interacted with, and the disnake.MessageInteraction.

In order to get the selected items that the user has chosen within the callback use UserSelect.values.

New in version 2.7.

Parameters:

  • cls (Callable[…, UserSelect]) – A callable (may be a UserSelect subclass) to create a new instance of this component. If provided, the other parameters described below do not apply. Instead, this decorator will accept the same keywords as the passed callable/class does.

  • placeholder (Optional[str]) – The placeholder text that is shown if nothing is selected, if any.

  • custom_id (str) – The ID of the select menu that gets received during an interaction. It is recommended not to set this parameter to prevent conflicts.

  • row (Optional[int]) – The relative row this select menu belongs to. A Discord component can only have 5 rows. By default, items are arranged automatically into those 5 rows. If you’d like to control the relative positioning of the row then passing an index is advised. For example, row=1 will show up before row=2. Defaults 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 1 and 25.

  • max_values (int) – The maximum number of items that must be chosen for this select menu. Defaults to 1 and must be between 1 and 25.

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

  • default_values (Optional[Sequence[Union[User, Member, SelectDefaultValue, Object]]]) –

    The list of values (users/members) that are selected by default. If set, the number of items must be within the bounds set by min_values and max_values.

    New in version 2.10.