Overview
Select menus (also known as dropdown menus) allow users to choose one or more options from a list. JDA supports string select menus and entity select menus for users, roles, channels, and mentionables.
Create a new string select menu builder.
The custom ID used to identify this menu (max 100 characters)
StringSelectMenu.java:135-136
static Builder create(@Nonnull String customId)
StringSelectMenu.java:47-60
StringSelectMenu menu = StringSelectMenu.create("menu:class")
.setPlaceholder("Choose your class") // shows the placeholder indicating what this menu is for
.setRequiredRange(1, 1) // exactly one must be selected
.addOption("Arcane Mage", "mage-arcane")
.addOption("Fire Mage", "mage-fire")
.addOption("Frost Mage", "mage-frost")
.setDefaultValues("mage-fire") // default to fire mage
.build();
event.reply("Please pick your class below")
.setEphemeral(true)
.addComponents(ActionRow.of(menu))
.queue();
ComponentsV2Example.java:176-182
ActionRow.of(
// For the sake of the example, this select menu will do nothing.
StringSelectMenu.create("feature")
.setPlaceholder("Select a module to configure")
.addOption("Moderation", "moderation", "Configure the moderation module")
.addOption("Fun", "fun", "Configure the fun module")
.setDefaultValues("moderation")
.build())
addOption()
Add a single option to the select menu.
The option label shown to users (max 100 characters)
The value received when selected (max 100 characters)
Optional description shown below the label
Builder addOption(@Nonnull String label, @Nonnull String value, @Nullable String description)
addOptions()
Add multiple SelectOption objects.
The options to add (max 25 total)
StringSelectMenu.java:163-164
Builder addOptions(@Nonnull SelectOption... options)
setPlaceholder()
Set the placeholder text shown when no option is selected.
The placeholder text (max 150 characters)
Builder setPlaceholder(@Nonnull String placeholder)
setRequiredRange()
Set the minimum and maximum number of options that can be selected.
Minimum selections (1-25)
Maximum selections (1-25)
Builder setRequiredRange(int min, int max)
setDefaultValues()
Set which options are selected by default.
The values of options to select by default
Builder setDefaultValues(@Nonnull String... values)
Select Options
SelectOption.of()
Create a select menu option.
The label displayed to users
The value received when this option is selected
static SelectOption of(@Nonnull String label, @Nonnull String value)
withEmoji()
Add an emoji to the option.
SelectOption withEmoji(@Nullable Emoji emoji)
withDescription()
Add a description to the option.
SelectOption withDescription(@Nullable String description)
withDefault()
Mark this option as selected by default.
Whether this option is selected by default
SelectOption withDefault(boolean isDefault)
StringSelectMenu menu = StringSelectMenu.create("roles")
.setPlaceholder("Select your roles")
.setRequiredRange(0, 3) // allow 0 to 3 selections
.addOption("Developer", "role:dev", "Software developer role")
.addOption("Designer", "role:design", "Designer role")
.addOption("Manager", "role:manager", "Project manager role")
.build();
event.reply("Choose up to 3 roles")
.addComponents(ActionRow.of(menu))
.queue();
Handling Select Menu Interactions
onStringSelectInteraction()
Listen for string select menu interactions.
@Override
public void onStringSelectInteraction(StringSelectInteractionEvent event) {
if (event.getComponentId().equals("menu:class")) {
String className = event.getValues().get(0);
event.reply("You selected: " + className)
.setEphemeral(true)
.queue();
}
}
Getting Selected Values
// Get all selected values
List<String> values = event.getValues();
// Get the first selected value
String firstValue = event.getValues().get(0);
// Get selected options with labels and descriptions
List<SelectOption> selectedOptions = event.getSelectedOptions();
The custom ID for this menu
targets
EntitySelectMenu.SelectTarget...
required
The types of entities to allow (USER, ROLE, CHANNEL)
EntitySelectMenu menu = EntitySelectMenu.create(
"select:members",
EntitySelectMenu.SelectTarget.USER
)
.setPlaceholder("Select a user")
.setRequiredRange(1, 1)
.build();
EntitySelectMenu userSelect = EntitySelectMenu.create(
"select:user",
EntitySelectMenu.SelectTarget.USER
)
.setPlaceholder("Select a user to mention")
.build();
event.reply("Who would you like to mention?")
.addComponents(ActionRow.of(userSelect))
.queue();
EntitySelectMenu channelSelect = EntitySelectMenu.create(
"select:channel",
EntitySelectMenu.SelectTarget.CHANNEL
)
.setPlaceholder("Select a channel")
.setChannelTypes(ChannelType.TEXT, ChannelType.NEWS)
.build();
getOptions()
Get the list of options (string select only).
StringSelectMenu.java:96-97
@Nonnull
List<SelectOption> getOptions()
getPlaceholder()
Get the placeholder text.
@Nullable
String getPlaceholder()
getMinValues()
Get the minimum number of required selections.
getMaxValues()
Get the maximum number of allowed selections.
getCustomId()
Get the custom ID for this select menu.
@Nonnull
String getCustomId()
asDisabled() / asEnabled()
Disable or enable the select menu.
StringSelectMenu.java:69-77
default StringSelectMenu asDisabled() {
return (StringSelectMenu) SelectMenu.super.asDisabled();
}
default StringSelectMenu asEnabled() {
return (StringSelectMenu) SelectMenu.super.asEnabled();
}
Action Rows
Select menus take up an entire action row and cannot be combined with other components in the same row.
event.reply("Configuration")
.addComponents(
ActionRow.of(selectMenu), // Select menu takes entire row
ActionRow.of(button1, button2, button3) // Buttons in separate row
)
.queue();
Constants
SelectMenu.OPTIONS_MAX_AMOUNT - Maximum of 25 options per select menuSelectMenu.ID_MAX_LENGTH - 100 characters maximum for custom IDsSelectMenu.PLACEHOLDER_MAX_LENGTH - 150 characters for placeholder text
Best Practices
Use setRequiredRange(1, 1) when you want users to select exactly one option, making it clear that selection is mandatory.
Select menus must have at least one option before building. The builder will throw an exception if you try to build an empty select menu.
User selections are session-specific and disappear when the client is restarted or the message is reloaded. Always handle the interaction to persist the selection.