ChoiceBox Overview

Woman working on a laptop at home
ONOKY - Eric Audras/Brand X Pictures/Getty Images

The ChoiceBox class is used to create a control which presents the user with a few choices to pick from a drop-down list. The user is only allowed to pick one of the options. When the drop-down list is not showing then the currently selected option is the only one visible. It is possible to set the ChoiceBox object to accept a null option as a valid choice.

Import Statement

import javafx.scene.control.ChoiceBox;


The ChoiceBox class has two constructors one for an empty list of items and one with a given set of items:

//Create an empty ChoiceBox
ChoiceBox choices = new ChoiceBox();
//Create a ChoiceBox using an observable list collection
ChoiceBox cboices = new ChoiceBox(FXCollections.observableArrayList("Apple", "Banana", "Orange", "Peach", "Pear", "Strawberry"));

Useful Methods

If you choose to create an empty ChoiceBox items can be added later using the setItems method:

choices.setItems(FXCollections.observableArrayList("Apple", "Banana", "Orange", "Peach", "Pear", "Strawberry"));

And, if you want to find out what items are in a ChoiceBox you can use the getItems method:

List options = choices.getItems();

To pick an option to be currently selected use the setValue method and provide it with one of the options:


To get the value of the option currently selected use the corresponding getValue method and assign it to a String:

String option = choices.getValue().toString();

Event Handling

In order to listen to events for a ChoiceBox object, the SelectionModel is used. The ChoiceBox uses the SingleSelectionModel class which only permits one option to be chosen at a time. The selectedIndexProperty method allows us to add a ChangeListener. This means that whenever the option selected changes to another option the change event will occur. As you can see from the code below, a change is listened for and when it occurs the previously selected option and the newly selected option can be determined:

final List options = choices.getItems();
choices.getSelectionModel().selectedIndexProperty().addListener(new ChangeListener() {
@Override public void changed(ObservableValue ov, Number oldSelected, Number newSelected) {
System.out.println("Old Selected Option: " + options.get(oldSelected.intValue()));
System.out.println("New Selected Option: " +options.get(newSelected.intValue()));

It's also possible to show or hide the list of options without the user having to click on the ChoiceBox object by using the show and hide methods. In the code below a Button object is used to call the show method of a ChoiceBox object when the Button is clicked:

//Use a stackpane for a simple layout of the controls
StackPane root = new StackPane();
//Create Button to show the options in the ChoiceBox
Button showOptionButton = new Button("Show Options");
root.setAlignment(showOptionButton, Pos.TOP_CENTER);
//Create the ChoiceBox with a few options
final ChoiceBox choices = new ChoiceBox(FXCollections.observableArrayList("Apple", "Banana", "Orange", "Peach", "Pear", "Strawberry"));
//Use the ActionEvent to call the ChoiceBox show method
showOptionButton.setOnAction(new EventHandler() {
@Override public void handle(ActionEvent e) {;
//Set the Scene and put the Stage into motion..
Scene scene = new Scene(root, 300, 250);

To find out about other JavaFX controls, have a look at JavaFX User Interface Controls.