How to use a selection Dropdown

Purpose. Offer single selection from a list of items, displayed as a button with an arrow that opens a popup (ListViewWindow) on tap. After choosing, the Dropdown’s text starts showing the selected item. Use it to choose among few/medium options without taking up fixed space on the screen.

APIs used

• new Dropdown(String placeholder, String[] items) — creates the dropdown with a placeholder text and the array of items.
• new Dropdown(String[] items) — variant with the default placeholder "Select...".
• dropdown.onSelect(Component.Action action) — callback fired after the user confirms the choice in the popup.
• dropdown.getSelectedIndex() — index of the selected item, or -1 if none.
• dropdown.getSelectedText() — text of the selected item, or null if none.
• dropdown.setSelectedIndex(int index) — selects programmatically and updates the displayed text.
• dropdown.popupHeightRatio(float) / dropdown.popupWidthRatio(float) — adjust the popup size relative to the screen.

Complete example (copy, paste, and run)

package com.exemplo;

import dev.crossfly.ui.*;
import dev.crossfly.ui.layout.*;

/** Runnable main screen. Point the launcher (classname) and run: gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      String[] estados = { "Acre", "Bahia", "São Paulo", "Paraná" };

      Dropdown uf = new Dropdown("Selecione o estado", estados);

      uf.onSelect(origin ->
      {
         int i = uf.getSelectedIndex();       // -1 if nothing chosen
         String texto = uf.getSelectedText(); // null if nothing chosen
         filtrarPorEstado(texto);
      });

      // Programmatic pre-selection (optional)
      uf.setSelectedIndex(2);   // "São Paulo"

      add(0.5f, uf);            // half width on the row (GridLayout)
   }

   private void filtrarPorEstado(String estado)
   {
      // ... filter the list by the chosen state ...
   }
}

The snippet below shows only the core. To run it, place it in the MainWindow skeleton above.

Minimal snippet

String[] estados = { "Acre", "Bahia", "São Paulo", "Paraná" };

Dropdown uf = new Dropdown("Selecione o estado", estados);

uf.onSelect(origin ->
{
   int i = uf.getSelectedIndex();       // -1 if nothing chosen
   String texto = uf.getSelectedText(); // null if nothing chosen
   filtrarPorEstado(texto);
});

// Programmatic pre-selection (optional)
uf.setSelectedIndex(2);   // "São Paulo"

add(0.5f, uf);            // half width on the row (GridLayout)

Verification note (2026 code). Confirmed in the source: Dropdown extends Button; constructors Dropdown(String placeholder, String[] items) and Dropdown(String[] items); onSelect(Action), getSelectedIndex(), getSelectedText(), setSelectedIndex(int). The popup decides on its own whether it opens above or below the dropdown depending on the space available on the screen, and closes when you tap outside. The onSelect callback runs after the selectedIndex/text have already been updated, so it is safe to call getSelectedText() inside it.

Dig deeper

• Widget page: Dropdown · Canonical source: Chapter 14
• Single/multiple selection with checkmarks: checkbox-e-radio.md