JavaFX GUI Development: Setup, Examples and a Calculator App

Q: Why does my JavaFX window freeze when I click a button?

Your button is probably doing slow work, like a long loop, Thread.sleep(), or a file or network call, on the JavaFX Application Thread. That thread also draws the screen, so the window stops responding. Move the slow work into a Task that runs on a background thread, and update the UI when the task finishes.

As a CS student, if you are confident about your Java programming skills and want to explore more advanced topics, then learning "JavaFX for GUI Development" is a great place to start.

JavaFX is the newest of Java's toolkits for building graphical user interfaces (GUIs), the windows, buttons, and text boxes you click on in a desktop app. In this article, we will first learn about JavaFX, how to set it up, its application structure, and some UI controls.

Later, we will look at practical examples of JavaFX, from CSS styling to animations, and then build a complete GUI calculator step by step. We compiled and ran every program on this page ourselves. So, let us start our discussion.

Summary Or Key Highlights:

With the JavaFX framework, we can build modern, good-looking desktop GUIs in Java.
JavaFX is no longer part of the JDK. Since Java 11, you download it separately (as OpenJFX) or add it through Maven or Gradle.
A JavaFX application is made of 4 important parts: the Application class, the Stage, the Scene, and Nodes.
JavaFX has ready-made UI controls like Button, Label, TextField, CheckBox, and more.
You can style an app with CSS, design its layout with FXML, add animations, and build full projects like a calculator.
From financial applications to IoT dashboards, the list of real-world uses of JavaFX is long.

In this guide:

What is JavaFX?
How to set up JavaFX
The JavaFX application structure
JavaFX UI controls
Practical examples: CSS, FXML, and animations
Worked example: a GUI calculator in JavaFX
JavaFX vs Swing vs AWT
Real-world applications
Third-party libraries
Performance tips
Common mistakes
Frequently asked questions

What Is JavaFX In GUI Development?

As developers, when we build desktop applications with Java, we need a graphical user interface to make the application easy and pleasant to use. JavaFX is a framework that helps us build that GUI.

JavaFX comes with modern features like CSS styling and FXML support, plus built-in charts, animations, and media playback. The best thing about JavaFX is that the same code runs on different operating systems, like Windows, macOS, and Linux.

Historical Evolution Of JavaFX In GUI Development:

1990s: The first Java GUI toolkit was AWT, which came with the first version of Java in 1996. It uses the operating system's own controls, so you can only customize it a little.
Late 1990s: Swing arrived and became part of Java in 1998. It gave us more UI components and much more flexibility. Swing is still included in the JDK today.
2008 to 2014: JavaFX 1.0 came out in 2008 with its own scripting language. JavaFX 2.0 (2011) switched to a normal Java API, and JavaFX 8 shipped inside JDK 8 in 2014.
2018 to today: Starting with Java 11, JavaFX was taken out of the JDK and became a separate open-source project called OpenJFX. It still gets a new release every six months, alongside the JDK.

How To Set Up JavaFX (It Is Not Part Of The JDK Anymore)

This is the first place most students get stuck. If you install a recent JDK and try to compile a JavaFX program the normal way, it fails right away:

HelloJav.java:1: error: package javafx.application does not exist
import javafx.application.Application;
                         ^

That happens because JavaFX has not been bundled with the standard JDK since Java 11. (A few JDK builds, like Liberica Full and Zulu FX, still include it, but most students use a JDK without it.) You have two easy ways to add it.

Option 1: Download the JavaFX SDK and use the command line. Download the JavaFX SDK for your operating system from the official OpenJFX site and unzip it. Then tell javac and java where the JavaFX files are and which parts (modules) you need:

javac --module-path path/to/javafx-sdk/lib --add-modules javafx.controls,javafx.fxml HelloJav.java
java --module-path path/to/javafx-sdk/lib --add-modules javafx.controls,javafx.fxml HelloJav

Replace path/to/javafx-sdk/lib with the real path to the lib folder you unzipped, for example C:\javafx-sdk\lib on Windows. The javafx.controls module gives you buttons, labels, and layouts. Add javafx.fxml only when your program uses FXML files.

If you skip the --module-path and --add-modules part when running, Java cannot find JavaFX at all:

Error: Could not find or load main class HelloJav
Caused by: java.lang.NoClassDefFoundError: javafx/application/Application

And if your IDE adds the JavaFX jar files to the classpath instead of the module path, you get a different error:

Error: JavaFX runtime components are missing, and are required to run this application

The fix is the same for both: load JavaFX with --module-path and --add-modules, or let a build tool do it for you.

Option 2: Use an IDE with Maven or Gradle. IntelliJ IDEA has a built-in JavaFX project wizard that sets everything up for you. The official Getting Started with JavaFX guide has step-by-step instructions for IntelliJ IDEA, NetBeans, Eclipse, and VS Code, with or without Maven and Gradle.

Which version should you use? At the time of writing (September 2026), the newest release is JavaFX 27, which needs JDK 25 or later. If your course uses an older JDK, pick an older JavaFX release that supports it. The JavaFX download page, linked from openjfx.io, lists which JDK each version needs.

What Is The JavaFX Application Structure?

Now that we have a basic definition of the JavaFX framework, it is time to move to some deeper concepts. In this section, we will talk about the structure of a JavaFX application. You need to understand this structure before you write your first program.

These are the key parts that work together to build a graphical user interface with JavaFX. Let us check the following list to know more about them.

Application Class: Every JavaFX program starts with a class that extends the Application class. When the program runs, main() calls launch(), JavaFX starts up, and then it calls your start() method. That is where you build your window.
Stage (Window): The Stage is the main application window. When you run a JavaFX program, the window that opens is the Stage. JavaFX passes the first one to start() for you, usually named primaryStage.
Scene (UI Container): The Scene holds everything you see inside the Stage. It has one root node, usually a layout like VBox or GridPane, and that root holds all the other UI components.
Nodes (UI Elements): Nodes are the basic building blocks of a JavaFX application. Every UI element, from buttons to shapes, is a node. The nodes inside a Scene form a tree called the scene graph.

What Are Some User Interface (UI) Controls In JavaFX?

After discussing the structure of a JavaFX application, it is time to look at some UI controls. In the JavaFX structure, these controls are nodes.

Before we start writing code, you should know the most used JavaFX UI controls. Let us check the following list.

Button: A basic button that runs some code when the user clicks it, for example to submit a form.
Label: Shows text that the user cannot edit.
TextField: Takes one line of input from the user.
TextArea: Takes multi-line input from the user.
CheckBox: A box the user can tick on or off. Use several of them when the user can pick more than one option.
TableView: Shows data in rows and columns, like a table.
ListView: Shows data as a list, and the user can select items from it.

What Are Some Practical Ways To Use JavaFX For GUI Development?

We hope what we have discussed so far clears up the basics of the JavaFX framework. So, in this section, we can move to practical examples.

After going through these practical ways to use JavaFX, your understanding of this topic will become much more solid. All three examples use the class name HelloJav, so put each one in its own folder, together with its CSS or FXML file. Then compile and run it with the commands from the setup section.

1. JavaFX With CSS Styles:

With JavaFX, we can use Cascading Style Sheets (CSS). Working with CSS in JavaFX is similar to web development, except that JavaFX property names start with -fx-. In the Java code, you give each element a style class name. After that, you can change how the app looks by editing only the CSS file, without touching the Java code.

HelloJav.java File:

import javafx.application.Application;
import javafx.scene.Scene;
import javafx.scene.control.Button;
import javafx.scene.control.Label;
import javafx.scene.layout.VBox;
import javafx.stage.Stage;

public class HelloJav extends Application // HelloJav Is Extending To Application
{

    @Override // Override Annotation Is Used
    public void start(Stage primaryStage)
    {
        // Creating The Label For The JavaFX Application
        Label l = new Label("JavaFX With CSS In CodingZap");
        l.getStyleClass().add("custom-label");

        // Implementing A Custom Button
        Button b = new Button("Check Our Blogs");
        b.getStyleClass().add("custom-button");

        // The VBox Layout Is Called With The Label And Button
        VBox v = new VBox(20, l, b);
        v.getStyleClass().add("root-container");

        // We Will Create A Scene With The VBox Layout
        Scene s = new Scene(v, 400, 200);
        // Calling The CSS File
        s.getStylesheets().add(getClass().getResource("zap.css").toExternalForm());

        primaryStage.setTitle("JavaFX with CSS");
        primaryStage.setScene(s); // Calling The Scene
        primaryStage.show();
    }

    public static void main(String[] args)
    {
        launch(args);
    }
}

The zap.css File:

.root-container
{
    -fx-background-color: blue;
    -fx-padding: 20px;
    -fx-alignment: center;
}

.custom-label
{
    -fx-font-size: 20px;
    -fx-text-fill: white;
}

.custom-button
{
    -fx-background-color: #3498DB;
    -fx-text-fill: white;
    -fx-font-size: 16px;
}

Steps Of The Application:

First, in the Java file, we import the classes for Application, Scene, Stage, Button, Label, and VBox.
Next, the HelloJav class extends the Application class to start the JavaFX program.
Execution starts from the start() method, where a Label is created to show a message.
Then, a Button is created with the text "Check Our Blogs".
Later, a VBox (the root container) is created with the Label and Button inside it, 20 pixels apart.
At last, we load the zap.css file into the Scene and show the Scene on the Stage.
The CSS file itself is written just like in web development. Each style class name, like .custom-button, matches a name we added in the Java code.

Output:

2. JavaFX With FXML For Design:

FXML is an XML-based language for describing the layout of a JavaFX screen. Instead of creating every button and label in Java code, you list them in an .fxml file, and JavaFX builds them for you. This keeps the layout separate from the Java logic, so you can change the layout by editing only the FXML file.

HelloJav.java File:

import javafx.application.Application;
import javafx.fxml.FXMLLoader;
import javafx.scene.Parent;
import javafx.scene.Scene;
import javafx.scene.control.Button;
import javafx.scene.control.Label;
import javafx.stage.Stage;

public class HelloJav extends Application // HelloJav Is Extending To Application
{

    @Override // Override Annotation Is Used
    public void start(Stage primaryStage) throws Exception
    {
        // Calling The FXML File
        FXMLLoader l = new FXMLLoader(getClass().getResource("zap.fxml"));
        Parent r = l.load();

        // We Will Find The UI Elements From The FXML File
        Label z = (Label) r.lookup("#z");
        Button o = (Button) r.lookup("#o");

        // We Will Handle The Button-Click Event With A Message
        o.setOnAction(event -> z.setText("The CodingZap Button Clicked!"));

        Scene s = new Scene(r, 300, 150);
        primaryStage.setTitle("JavaFX with FXML");
        primaryStage.setScene(s); // Calling The Scene
        primaryStage.show();
    }

    public static void main(String[] args)
    {
        launch(args);
    }
}

The zap.fxml File:

<?xml version="1.0" encoding="UTF-8"?>

<?import javafx.scene.control.*?>
<?import javafx.scene.layout.*?>

<VBox xmlns:fx="http://javafx.com/fxml" spacing="10" alignment="CENTER">

    <Label fx:id="z" text="JavaFX with FXML!"/>
    <Button fx:id="o" text="Click On CodingZap"/>

</VBox>

Steps Of The Application:

In the Java file, we import the classes for Application, FXMLLoader, Parent, Scene, Label, Button, and Stage.
Now, the HelloJav class extends Application, and JavaFX calls its start() method.
First, we load the zap.fxml file, and JavaFX creates all the elements listed in it.
Later, we find the Label and Button by their fx:id using lookup(). The # in "#z" means "find by id", just like in CSS.
Also, we give the Button an action that changes the Label's text when we click it.
In the end, we put the loaded layout in a Scene and show it on the Stage.
The ids in the FXML file (z and o) must match the ids we look up in the Java code.

Using lookup() is fine for a small demo. In bigger apps, the usual way is a separate controller class with @FXML fields, linked from the FXML file with fx:controller. Keeping the layout (FXML) and the logic (controller) apart is the same idea behind MVC architecture in Java. Gluon's free Scene Builder tool lets you design FXML screens by dragging and dropping.

Output Before Clicking The Button:

Output After Clicking The Button:

3. Smooth Animations With JavaFX:

With JavaFX, we can add animations too. JavaFX has built-in transitions like fading, moving, rotating, and scaling. In the following program, we use two of them to make a button slide and fade when it is clicked.

import javafx.animation.FadeTransition;
import javafx.animation.TranslateTransition;
import javafx.application.Application;
import javafx.scene.Scene;
import javafx.scene.control.Button;
import javafx.scene.layout.StackPane;
import javafx.stage.Stage;
import javafx.util.Duration;

public class HelloJav extends Application // HelloJav Is Extending To Application
{

    @Override // Override Annotation Is Used
    public void start(Stage primaryStage)
    {
        Button b = new Button("Click On CodingZap");

        // We Are Implementing Smooth Move Animation
        TranslateTransition m = new TranslateTransition(Duration.seconds(1), b);

        m.setByX(100);  // We Will Move 100 Pixels To The Right On The X-Axis
        m.setAutoReverse(true); // Then Come Back
        m.setCycleCount(2); // One Trip Out And One Trip Back

        // We Are Implementing The Fade Animation Effect
        FadeTransition f = new FadeTransition(Duration.seconds(1), b);
        f.setFromValue(1.0);
        f.setToValue(0.3);
        f.setAutoReverse(true);
        f.setCycleCount(2);

        // The Animation Will Be Done When We Click On The Button
        b.setOnAction(e -> {
            m.play();
            f.play();
        });

        StackPane r = new StackPane(b);
        r.setStyle("-fx-padding: 20px;");

        Scene s = new Scene(r, 400, 300); // We Are Creating The Scene

        primaryStage.setTitle("JavaFX Animations");
        primaryStage.setScene(s); // We Are Calling The Scene
        primaryStage.show();
    }

    public static void main(String[] args)
    {
        launch(args);
    }
}

Steps Of The Application:

First, we import the classes for Application, Stage, Button, Scene, StackPane, and the two animations: FadeTransition and TranslateTransition.
As before, the HelloJav class extends Application and builds everything in start().
We make a Button with the text "Click On CodingZap".
Next, we create the move animation. It slides the button 100 pixels to the right in one second. Because auto reverse is on and the cycle count is 2, it then slides back to where it started.
After that, we create the fade animation. It fades the button to 30% opacity and then back to full, in the same two seconds.
When the button is clicked, both animations play at the same time.
In the end, the Scene is set on the Stage, and the window is shown.

Output: When you click the button, it slides to the right while fading out, then slides back and fades in again. The whole effect takes about two seconds, and the button ends up exactly where it started.

Worked Example: Build A GUI Calculator With JavaFX

Now let us put everything together in a real project. A GUI calculator is one of the most common JavaFX assignments, and it is a great first project because it uses layouts, buttons, styles, and event handling all at once. If you want more projects at this level, check out our list of Java project ideas.

In this section, we will walk through a JavaFX GUI calculator, from the assignment sheet to the working app.

What Are The Requirements Of A Typical JavaFX Calculator Assignment?

Before we start building the calculator, we have to go through the assignment sheet. Once we understand it, we know exactly what the app must do. Here are the requirements of a typical JavaFX GUI calculator assignment:

Create a desktop GUI calculator (an app that opens in its own window) with JavaFX.
There should be a display screen to show the inputs and outputs.
There should be buttons for the digits, the operations, Clear (C), and Equals (=).
The calculator should do the basic arithmetic operations: add, subtract, multiply, and divide.
The calculator should handle bad input and errors, like dividing by zero, without crashing.

What JavaFX Components Are Used In The GUI Calculator?

The first step is to decide which JavaFX components we need. This list works as the blueprint for the code:

TextField: The display area that shows the numbers and results.
Button: The digit, operation, Clear (C), and Equals (=) buttons.
GridPane: Places all the calculator buttons in a 4x4 grid.
MouseEvent: Changes a button's color while it is being pressed, so the user gets visual feedback.
VBox: Stacks the TextField and the GridPane vertically in the main layout.
Scene: Holds the entire main layout and displays it.
Stage: The main window that shows the Scene.

What Are The Different Sections In The JavaFX Calculator Code?

To make it easier to follow, we have divided the complete calculator code into 6 sections. All six sections go into one file named ZapCalculator.java, in this order. Put them together, then compile and run the file with the commands from the setup section, replacing HelloJav with ZapCalculator. The calculator window will open.

Section 1: Necessary Imported Packages

To build anything with JavaFX, we have to import several classes. That is why we start with a separate section for the imports. Without them, the compiler would not know what a Button or a GridPane is.

// We Will Import Necessary Packages For JavaFX
import javafx.application.Application;
import javafx.geometry.Pos;
import javafx.scene.Scene;
import javafx.scene.control.Button;
import javafx.scene.control.TextField;
import javafx.scene.input.MouseEvent;
import javafx.scene.layout.GridPane;
import javafx.scene.layout.VBox;
import javafx.stage.Stage;