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 (float | None) – 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:

float | None

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 (float | None) – The timeout of the converted view.

Raises:

TypeError – Message contains v2 components, which are not supported by View. See also MessageFlags.is_components_v2.

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, id=0)[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. Note that this means empty rows will be considered falsy.

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.

  • id (int) –

    The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

property children[source]

Sequence[WrappedComponent]: A read-only proxy 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, id=0)[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 (str | None) – The ID of the button that gets received during an interaction. If this button is for a URL, it does not have a custom ID.

  • url (str | None) – The URL this button sends you to.

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

  • label (str | None) – The label of the button, if any.

  • emoji (PartialEmoji | Emoji | str | None) – The emoji of the button, if available.

  • sku_id (int | None) –

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

    New in version 2.11.

  • id (int) –

    The numeric identifier for the component. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    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, id=0)[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 (str | None) – The placeholder text that is shown if nothing is selected, if any.

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

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

  • options (list[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.

  • id (int) –

    The numeric identifier for the component. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

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, id=0)[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 (str | None) – 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 (Sequence[User | Member | SelectDefaultValue | Object] | None) –

    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.

  • id (int) –

    The numeric identifier for the component. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

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, id=0)[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 (str | None) – 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 (Sequence[Role | SelectDefaultValue | Object] | None) –

    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.

  • id (int) –

    The numeric identifier for the component. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

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, id=0)[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 (str | None) – 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 (Sequence[User | Member | Role | SelectDefaultValue] | None) –

    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.

  • id (int) –

    The numeric identifier for the component. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

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, id=0)[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 (str | None) – 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 (list[ChannelType] | None) – The list of channel types that can be selected in this select menu. Defaults to all types (i.e. None).

  • default_values (Sequence[abc.GuildChannel | Thread | abc.PrivateChannel | PartialMessageable | SelectDefaultValue | Object] | None) –

    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.

  • id (int) –

    The numeric identifier for the component. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

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, id=0)[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.

Deprecated since version 2.11: Use of action rows in modals is deprecated, use Label("<text>", TextInput(...)) directly instead.

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 (str | None) – The placeholder text that is shown if nothing is entered.

  • value (str | None) – The pre-filled value of the text input.

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

  • min_length (int | None) – The minimum length of the text input.

  • max_length (int | None) – The maximum length of the text input.

  • id (int) –

    The numeric identifier for the component. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

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(*, id=0)[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.

Deprecated since version 2.11: Use of action rows in modals is deprecated, compatible components can be passed directly to modals.

Returns:

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

Return type:

ActionRow

classmethod with_message_components(*, id=0)[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.

Note

This only supports ActionRows and associated components, i.e. no v2 components. See ui.components_from_message() for a function that supports all component types.

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 or message uses v2 components (see also MessageFlags.is_components_v2).

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.

Note

This only supports ActionRows, i.e. no v2 components. See ui.walk_components() for a function that supports all component types.

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 interactive 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:

View | None

await callback(interaction, /)[source]

This function is a coroutine.

The callback associated with this UI item.

This can be overridden by subclasses.

Parameters:

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

WrappedComponent

class disnake.ui.WrappedComponent[source]

Represents the base UI component that all ActionRow-compatible UI components inherit from.

This class adds more functionality on top of the UIComponent base class, specifically for action rows.

The following classes implement this ABC:

New in version 2.4.

UIComponent

Attributes
class disnake.ui.UIComponent[source]

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

The following classes implement this ABC:

New in version 2.11.

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

Button

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

Represents a UI button.

New in version 2.0.

Parameters:

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

  • custom_id (str | None) – 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 (str | None) – The URL this button sends you to.

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

  • label (str | None) – The label of the button, if any.

  • emoji (PartialEmoji | Emoji | str | None) – The emoji of the button, if available.

  • sku_id (int | None) –

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

    New in version 2.11.

  • id (int) –

    The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

  • row (int | None) – 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:

str | None

property url[source]

The URL this button sends you to.

Type:

str | None

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 overridden by subclasses.

Parameters:

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

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

property view[source]

The underlying view for this item.

Type:

View | None

property label[source]

The label of the button, if available.

Type:

str | None

property emoji[source]

The emoji of the button, if available.

Type:

PartialEmoji | None

property sku_id[source]

The ID of a purchasable SKU, for premium buttons.

New in version 2.11.

Type:

int | None

BaseSelect

Attributes
Methods
class disnake.ui.BaseSelect[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:

str | None

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 overridden by subclasses.

Parameters:

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

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

property required[source]

Whether the select menu is required. Only applies to components in modals.

New in version 2.11.

Type:

bool

property view[source]

The underlying view for this item.

Type:

View | None

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, disabled=False, options=..., required=True, id=0, 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 (str | None) – 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.

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

  • required (bool) –

    Whether the select menu is required. Only applies to components in modals. Defaults to True.

    New in version 2.11.

  • id (int) –

    The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

  • row (int | None) – 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 (str | None) – An additional description of the option, if any. Can only be up to 100 characters.

  • emoji (str | Emoji | PartialEmoji | None) – 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 overridden 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

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

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:

str | None

property required[source]

Whether the select menu is required. Only applies to components in modals.

New in version 2.11.

Type:

bool

property view[source]

The underlying view for this item.

Type:

View | None

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, required=True, id=0, 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 (str | None) – 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 (list[ChannelType] | None) – The list of channel types that can be selected in this select menu. Defaults to all types (i.e. None).

  • default_values (Sequence[abc.GuildChannel | Thread | abc.PrivateChannel | PartialMessageable | SelectDefaultValue | Object] | None) –

    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.

  • required (bool) –

    Whether the select menu is required. Only applies to components in modals. Defaults to True.

    New in version 2.11.

  • id (int) –

    The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

  • row (int | None) – 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[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 overridden 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:

list[disnake.ChannelType] | None

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

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

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:

str | None

property required[source]

Whether the select menu is required. Only applies to components in modals.

New in version 2.11.

Type:

bool

property view[source]

The underlying view for this item.

Type:

View | None

MentionableSelect

Attributes
Methods
class disnake.ui.MentionableSelect(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None, required=True, id=0, 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 (str | None) – 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 (Sequence[User | Member | Role | SelectDefaultValue] | None) –

    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.

  • required (bool) –

    Whether the select menu is required. Only applies to components in modals. Defaults to True.

    New in version 2.11.

  • id (int) –

    The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

  • row (int | None) – 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[User | Member | Role]

await callback(interaction, /)[source]

This function is a coroutine.

The callback associated with this UI item.

This can be overridden 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

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

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:

str | None

property required[source]

Whether the select menu is required. Only applies to components in modals.

New in version 2.11.

Type:

bool

property view[source]

The underlying view for this item.

Type:

View | None

RoleSelect

Attributes
Methods
class disnake.ui.RoleSelect(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None, required=True, id=0, 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 (str | None) – 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 (Sequence[Role | SelectDefaultValue | Object] | None) –

    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.

  • required (bool) –

    Whether the select menu is required. Only applies to components in modals. Defaults to True.

    New in version 2.11.

  • id (int) –

    The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

  • row (int | None) – 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 overridden 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

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

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:

str | None

property required[source]

Whether the select menu is required. Only applies to components in modals.

New in version 2.11.

Type:

bool

property view[source]

The underlying view for this item.

Type:

View | None

UserSelect

Attributes
Methods
class disnake.ui.UserSelect(*, custom_id=..., placeholder=None, min_values=1, max_values=1, disabled=False, default_values=None, required=True, id=0, 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 (str | None) – 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 (Sequence[User | Member | SelectDefaultValue | Object] | None) –

    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.

  • required (bool) –

    Whether the select menu is required. Only applies to components in modals. Defaults to True.

    New in version 2.11.

  • id (int) –

    The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

  • row (int | None) – 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 overridden 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

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

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:

str | None

property required[source]

Whether the select menu is required. Only applies to components in modals.

New in version 2.11.

Type:

bool

property view[source]

The underlying view for this item.

Type:

View | None

TextInput

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

Represents a UI text input.

This can only be used in a Modal.

New in version 2.4.

Parameters:

  • label (str | None) –

    The label of the text input.

    Deprecated since version 2.11: This is deprecated in favor of Label.text and .description.

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

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

  • placeholder (str | None) – The placeholder text that is shown if nothing is entered.

  • value (str | None) – The pre-filled value of the text input.

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

  • min_length (int | None) – The minimum length of the text input.

  • max_length (int | None) – The maximum length of the text input.

  • id (int) –

    The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

property style[source]

The style of the text input.

Type:

TextInputStyle

property label[source]

The label of the text input.

Deprecated since version 2.11: This is deprecated in favor of ui.Label.

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:

str | None

property value[source]

The pre-filled text of the text input.

Type:

str | None

property required[source]

Whether the text input is required.

Type:

bool

property min_length[source]

The minimum length of the text input.

Type:

int | None

property max_length[source]

The maximum length of the text input.

Type:

int | None

Section

Attributes
class disnake.ui.Section(*components, accessory, id=0)[source]

Represents a UI section.

This allows displaying an accessory (thumbnail or button) next to a block of text.

New in version 2.11.

Parameters:

  • *components (str | TextDisplay) – The text items in this section (up to 3).

  • accessory (Thumbnail | Button) – The accessory component displayed next to the section text.

  • id (int) – The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

children

The list of text items in this section.

Type:

list[TextDisplay]

accessory

The accessory component displayed next to the section text.

Type:

Thumbnail | Button

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

TextDisplay

Attributes
class disnake.ui.TextDisplay(content, *, id=0)[source]

Represents a UI text display.

New in version 2.11.

Parameters:

  • content (str) – The text displayed by this component.

  • id (int) – The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

property content[source]

The text displayed by this component.

Type:

str

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

Thumbnail

Attributes
class disnake.ui.Thumbnail(media, description=None, *, spoiler=False, id=0)[source]

Represents a UI thumbnail.

This is only supported as the accessory of a section component.

New in version 2.11.

Parameters:

  • media (str | Asset | Attachment | UnfurledMediaItem) – The media item to display. Can be an arbitrary URL or attachment reference (attachment://<filename>).

  • description (str | None) – The thumbnail’s description (“alt text”), if any.

  • spoiler (bool) – Whether the thumbnail is marked as a spoiler. Defaults to False.

  • id (int) – The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

property media[source]

The media item to display.

Type:

UnfurledMediaItem

property description[source]

The thumbnail’s description (“alt text”), if any.

Type:

str | None

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

property spoiler[source]

Whether the thumbnail is marked as a spoiler.

Type:

bool

MediaGallery

Attributes
class disnake.ui.MediaGallery(*items, id=0)[source]

Represents a UI media gallery.

This allows displaying up to 10 images in a gallery.

New in version 2.11.

Parameters:

  • *items (MediaGalleryItem) – The list of images in this gallery (up to 10).

  • id (int) – The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

property items[source]

The images in this gallery.

Type:

list[MediaGalleryItem]

File

Attributes
class disnake.ui.File(file, *, spoiler=False, id=0)[source]

Represents a UI file component.

New in version 2.11.

Parameters:

  • file (str | UnfurledMediaItem) – The file to display. This only supports attachment references (i.e. using the attachment://<filename> syntax), not arbitrary URLs.

  • spoiler (bool) – Whether the file is marked as a spoiler. Defaults to False.

  • id (int) – The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

property file[source]

The file to display.

Type:

UnfurledMediaItem

property spoiler[source]

Whether the file is marked as a spoiler.

Type:

bool

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

property name[source]

The name of the file. This is available in objects from the API, and ignored when sending.

Type:

str | None

property size[source]

The size of the file. This is available in objects from the API, and ignored when sending.

Type:

int | None

Separator

Attributes
class disnake.ui.Separator(*, divider=True, spacing=SeparatorSpacing.small, id=0)[source]

Represents a UI separator.

New in version 2.11.

Parameters:

  • divider (bool) – Whether the separator should be visible, instead of just being vertical padding/spacing. Defaults to True.

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

  • id (int) – The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

property divider[source]

Whether the separator should be visible, instead of just being vertical padding/spacing.

Type:

bool

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

property spacing[source]

The size of the separator.

Type:

SeparatorSpacing

Container

Attributes
class disnake.ui.Container(*components, accent_colour=None, spoiler=False, id=0)[source]

Represents a UI container.

This is visually similar to Embeds, and contains other components.

New in version 2.11.

Parameters:

  • *components (ActionRow | Section | TextDisplay | MediaGallery | File | Separator) – The components in this container.

  • accent_colour (Colour | None) – The accent colour of the container.

  • spoiler (bool) – Whether the container is marked as a spoiler. Defaults to False.

  • id (int) – The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

children

The list of child components in this container.

Type:

list[ActionRow | Section | TextDisplay | MediaGallery | File | Separator]

accent_colour[source]

The accent colour of the container. An alias exists under accent_color.

Type:

Colour | None

spoiler

Whether the container is marked as a spoiler.

Type:

bool

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

Label

Attributes
class disnake.ui.Label(text, component, *, description=None, id=0)[source]

Represents a UI label.

This wraps other components with a label and an optional description, and can only be used in modals.

New in version 2.11.

Parameters:

  • text (str) – The label text.

  • component (TextInput | FileUpload | BaseSelect) – The component within the label. Currently supports ui.TextInput, ui.FileUpload, and select menus (e.g. ui.StringSelect).

  • description (str | None) – The description text for the label.

  • id (int) – The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

text

The label text.

Type:

str

component

The component within the label.

Type:

TextInput | FileUpload | BaseSelect

description

The description text for the label.

Type:

str | None

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

FileUpload

Attributes
class disnake.ui.FileUpload(*, custom_id=..., min_values=1, max_values=1, required=True, id=0)[source]

Represents a UI file upload.

New in version 2.12.0a.

Parameters:

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

  • min_values (int) – The minimum number of files that must be uploaded. Defaults to 1 and must be between 0 and 10.

  • max_values (int) – The maximum number of files that must be uploaded. Defaults to 1 and must be between 1 and 10.

  • required (bool) – Whether the file upload is required. Defaults to True.

  • id (int) – The numeric identifier for the component. Must be unique within the modal. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the modal.

property custom_id[source]

The ID of the file upload that gets received during an interaction.

Type:

str

property min_values[source]

The minimum number of files that must be uploaded.

Type:

int

property id[source]

The numeric identifier for the component. This is always present in components received from the API, and unique within a message.

New in version 2.11.

Type:

int

property max_values[source]

The maximum number of files that must be uploaded.

Type:

int

property required[source]

Whether the select menu is required.

Type:

bool

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 (str | None) – The label of the button, if any.

  • custom_id (str | None) – 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 (str | Emoji | PartialEmoji | None) – The emoji of the button. This can be in string form or a PartialEmoji or a full Emoji.

  • id (int) –

    The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

  • row (int | None) – 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 (str | None) – 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.

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

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

  • options (list[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.

  • id (int) –

    The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

  • row (int | None) – 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).

@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 (str | None) – 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.

  • 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 (list[ChannelType] | None) – The list of channel types that can be selected in this select menu. Defaults to all types (i.e. None).

  • default_values (Sequence[abc.GuildChannel | Thread | abc.PrivateChannel | PartialMessageable | SelectDefaultValue | Object] | None) –

    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.

  • id (int) –

    The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

  • row (int | None) – 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).

@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 (str | None) – 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.

  • 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 (Sequence[User | Member | Role | SelectDefaultValue] | None) –

    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.

  • id (int) –

    The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

  • row (int | None) – 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).

@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 (str | None) – 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.

  • 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 (Sequence[Role | SelectDefaultValue | Object] | None) –

    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.

  • id (int) –

    The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

  • row (int | None) – 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).

@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 (str | None) – 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.

  • 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 (Sequence[User | Member | SelectDefaultValue | Object] | None) –

    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.

  • id (int) –

    The numeric identifier for the component. Must be unique within the message. If set to 0 (the default) when sending a component, the API will assign sequential identifiers to the components in the message.

    New in version 2.11.

  • row (int | None) – 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).

for ... in disnake.ui.walk_components(components)[source]

Iterate over given components, yielding each individual component, including child components where applicable (e.g. for ActionRow and Container).

New in version 2.11.

Parameters:

components (Sequence[Component] | Sequence[UIComponent]) – The sequence of components to iterate over. This supports both disnake.Component objects and ui.UIComponent objects.

Yields:

Component | UIComponent – A component from the given sequence or child component thereof.

disnake.ui.components_from_message(message)[source]

Create a list of UIComponents from the components of an existing message.

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

New in version 2.11.

Parameters:

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

Raises:

TypeError – An unknown component type is encountered.

Returns:

The ui components parsed from the components on the message.

Return type:

list[UIComponent]