Skip to main content
Select menus are dropdown menus that allow users to choose one or more options.

​
Select

Represents a UI select menu. 
from discord.ui import Select
import discord

select = Select(
    placeholder="Choose an option",
    options=[
        discord.SelectOption(label="Option 1", value="1"),
        discord.SelectOption(label="Option 2", value="2"),
    ]
)

​
Constructor

​
select_type
ComponentType
default:"ComponentType.string_select"
The type of select to create. Must be one of: string_select, user_select, role_select, mentionable_select, or channel_select.
​
custom_id
str | None
default:"None"
The ID of the select menu. Auto-generated if not provided.
​
placeholder
str | None
default:"None"
The placeholder text shown if nothing is selected. Maximum of 150 characters.
​
min_values
int
default:"1"
The minimum number of items that must be chosen. Must be between 0 and 25.
​
max_values
int
default:"1"
The maximum number of items that can be chosen. Must be between 1 and 25.
​
options
List[SelectOption]
default:"None"
A list of options that can be selected. Only valid for string_select.
​
channel_types
List[ChannelType]
default:"None"
A list of channel types that can be selected. Only valid for channel_select.
​
disabled
bool
default:"False"
Whether the select is disabled or not.
​
row
int | None
default:"None"
The relative row this select menu belongs to (0-4).
​
id
int | None
default:"None"
The select menu’s ID.
​
required
bool | None
default:"None"
Whether the select is required or not. Only applicable in modals.
​
default_values
Sequence[SelectDefaultValue | Snowflake] | None
default:"None"
The default values of this select. Only applicable for non-string selects.

​
Attributes

​
custom_id
str
The ID of the select menu.
​
placeholder
str | None
The placeholder text that is shown if nothing is selected.
​
min_values
int
The minimum number of items that must be chosen.
​
max_values
int
The maximum number of items that can be chosen.
​
disabled
bool
Whether the select is disabled or not.
​
required
bool
Whether the select is required or not.
​
options
List[SelectOption]
A list of options that can be selected. Only for string selects.
​
channel_types
List[ChannelType]
A list of channel types that can be selected. Only for channel selects.
​
default_values
List[SelectDefaultValue]
A list of the select’s default values.
​
values
List[str] | List[User | Member] | List[Role] | List[GuildChannel] | None
A list of values that have been selected by the user. None if not yet interacted with.
​
width
int
The width of the select menu in the UI layout. Always 5.
​
row
int | None
The row position of this select menu (0-4).

​
Methods

Adds an option to the select menu (string selects only).Parameters:
  • label (str): The label of the option (max 100 chars).
  • value (str): The value of the option (max 100 chars). Defaults to label.
  • description (str | None): An additional description (max 100 chars).
  • emoji (str | PartialEmoji | None): The emoji of the option.
  • default (bool): Whether this option is selected by default.
Raises:
  • ValueError: The number of options exceeds 25.
select.add_option(label="Option 1", value="1", emoji="🎉")
Appends a pre-existing SelectOption to the select menu.Parameters:
  • option (SelectOption): The option to append.
Raises:
  • ValueError: The number of options exceeds 25.
option = discord.SelectOption(label="Option 1", value="1")
select.append_option(option)
Adds a default value to the select menu.Parameters:
  • id (int): The ID of the entity to add as a default.
  • type (SelectDefaultValueType): The default value type. Required for mentionable selects.
Raises:
  • TypeError: Invalid type or select type is string_select.
  • ValueError: Number of default values exceeds 25.
select.add_default_value(id=123456789, type=discord.SelectDefaultValueType.user)
Appends a default value to this select menu.Parameters:
  • value (SelectDefaultValue | Snowflake): The default value to append.
Raises:
  • TypeError: The select type is string_select.
  • ValueError: Number of default values exceeds 25.
default = discord.SelectDefaultValue(id=123456789, type=discord.SelectDefaultValueType.user)
select.append_default_value(default)
The callback associated with this select menu. Override in subclasses or use the decorator.Parameters:
  • interaction (Interaction): The interaction that triggered this select.
async def callback(self, interaction: discord.Interaction):
    await interaction.response.send_message(f"You selected: {self.values}")

​
Select Type Aliases

Convenience aliases for creating specific types of selects:
An alias for Select with select_type=ComponentType.string_select.
from discord.ui import StringSelect

select = StringSelect(
    placeholder="Choose a color",
    options=[
        discord.SelectOption(label="Red", value="red", emoji="🔴"),
        discord.SelectOption(label="Blue", value="blue", emoji="🔵"),
    ]
)

​
Select Decorators

Decorators for attaching select menus to views:

​
@select

@discord.ui.select(
    select_type=discord.ComponentType.string_select,
    placeholder="Choose an option",
    options=[
        discord.SelectOption(label="Option 1", value="1"),
        discord.SelectOption(label="Option 2", value="2"),
    ]
)
async def my_select(self, select: discord.ui.Select, interaction: discord.Interaction):
    await interaction.response.send_message(f"You chose: {select.values[0]}")

​
Convenience Decorators

  • @string_select() - String select
  • @user_select() - User select
  • @role_select() - Role select
  • @channel_select() - Channel select
  • @mentionable_select() - Mentionable select

​
Examples

import discord
from discord.ui import View, Select

class ColorView(View):
    @discord.ui.string_select(
        placeholder="Choose a color",
        options=[
            discord.SelectOption(label="Red", value="red", emoji="🔴"),
            discord.SelectOption(label="Blue", value="blue", emoji="🔵"),
            discord.SelectOption(label="Green", value="green", emoji="🟢"),
        ]
    )
    async def color_select(self, select: Select, interaction: discord.Interaction):
        color = select.values[0]
        await interaction.response.send_message(f"You selected {color}!", ephemeral=True)

view = ColorView()
await ctx.send("Pick a color:", view=view)

Build docs developers (and LLMs) love

Get started for freeTalk to us