# How to use a selection Dropdown

> Open a drop-down list, react to the choice, and get the selected item.

Source: https://crossfly.dev/docs/cookbook/ui/dropdown-selecao — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# 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)
```java
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
```java
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](/docs/ui/widgets/dropdown) · Canonical source: Chapter 14
- Single/multiple selection with checkmarks: [checkbox-e-radio.md](/docs/cookbook/ui/checkbox-e-radio)