GemsFX is a JavaFX control library whose demo app doubles as its manual

Sixty controls, and a demo application instead of a website gallery

GemsFX is a collection of custom controls and utilities for JavaFX. The library ships around 60 controls and utilities, each with its own developer manual, and the readme is organised by category rather than by class name.

The date and time group alone contains CalendarView, CalendarPicker, DateRangeView, DateRangePicker, YearView, YearPicker, YearMonthView, YearMonthPicker, TimePicker, TimeRangePicker, DurationPicker and DayOfWeekPicker. Text and input brings SearchTextField, EnhancedPasswordField, EmailField, TagsField, ChipView, ExpandingTextArea and others. Lists and tables covers AdvancedTableView, FilterView, GridTableView, MultiColumnListView and the paging family. Layout, images and graphics, feedback and progress, and a utilities group with SessionManager, StageManager and HistoryManager complete the list.

What makes the library unusual is the demo application module, which the readme calls the central entry point for exploring GemsFX. It lists every control in one place so you can find one, read its documentation and see it working without writing a line of code. Controls are grouped by category and filtered through a search field, selecting a control opens the PDF manual from docs/manuals inside the application, and double-clicking launches that control's own demo application.

A detail that shows the level of care: the demo application uses AtlantaFX, so you can switch theme family and move between light, dark and the system colour scheme to see how the controls behave under each.

Java 11 for the library, Java 24 for the demos

The version story is split by module, and the split is deliberate.

The gemsfx library module targets Java 11 and JavaFX 17 or later. Those are the numbers that matter if you are putting GemsFX into your own application, because they are the floor your runtime has to clear.

The gemsfx-demo module and the demo application module are on a much newer baseline, Java 24 with JavaFX 25.0.2. Those two are developer tools rather than shipped dependencies, so the project can build them against a current JDK while keeping the library consumable by applications that are not ready to move.

That is a sensible arrangement, and it has a practical consequence. You can consume GemsFX from a Java 11 project with JavaFX 17, but if you clone the repository to work on the controls themselves, or simply want to run the demo application locally, you need a current JDK. The readme mentions two ways to see the library in action, one of which is running the demo application with Maven and the other is installing a demo launcher through jdeploy, and that launcher updates itself whenever a new version of GemsFX is released.

The library is published to Maven Central under the coordinates com.dlsc.gemsfx/gemsfx, and the complete API documentation is published at gemsfx.dlsc.com with the PDF manuals kept in the repository under docs/manuals.

Running the demo application and launching a single control

The demo application is a Maven module with a JavaFX run configuration, so the whole thing starts with one command from the repository root.

mvn javafx:run -f gemsfx-showcase/pom.xml

That gives you a window with every control grouped by category and a search field to filter them. Three interactions carry most of the value.

Selecting a control opens its developer manual, the PDFs from docs/manuals, directly inside the application, so the documentation is read next to the running control rather than on another tab. Double-clicking a control launches the demo application for that control, and a shift double-click also opens the developer tools for the launched demo, which is how you inspect the scene tree when a control is not behaving.

For people who do not want to clone the repository, the alternative is the demo launcher, which the readme says can be installed locally via jdeploy. Its one advantage over the Maven route is that it updates itself whenever a new version of GemsFX is released, so you can watch the library change without re-running a build.

Both routes exist because the demo application is the project's primary documentation surface. The readme tells newcomers to start with it rather than with a tutorial.

Tests need a real toolkit, so they run headless on Monocle

The unit tests of the gemsfx module create real controls, which means they need a running JavaFX toolkit. On a developer laptop that is fine, on a CI server without a display it is a problem.

The project's answer is Monocle, the headless platform from TestFX. The required system properties, glass.platform=Monocle, monocle.platform=Headless and prism.order=sw among them, are configured for the surefire plugin in gemsfx/pom.xml, so no extra setup such as Xvfb is needed on the build machine.

The second piece is a shared base class. All tests that need the toolkit extend com.dlsc.gemsfx.FxTestBase, which starts the toolkit once per JVM and offers helpers to run code on the JavaFX application thread through runFx and invoke, and to force skin creation through layout. That last helper matters more than it looks: a JavaFX control is not fully realised until its skin is created, so a test that never forces layout can pass without ever exercising the rendering path it claims to cover.

Both the full run and a single class are one command.

# run all tests of the library module
./mvnw test -pl gemsfx

# run a single test class
./mvnw test -pl gemsfx -Dtest=CalendarViewTest

DocLint is what stops an undocumented control being published

Most component libraries treat documentation as a matter of taste. GemsFX treats it as a build condition, and this is the most distinctive thing about the project.

The published gemsfx module is held to a strict documentation standard, enforced by the Java compiler's DocLint checker. The maven-javadoc-plugin in the root pom.xml runs with doclint set to all for the library, which validates syntax, HTML, accessibility and cross-references, and also reports every undocumented public or protected type, method, constructor and field. Warnings do not break the build, but errors such as broken link references do.

The rules for new code are written out. Every public and protected member carries a Javadoc comment. The param, return and throws tags are complete, including type parameters. For a JavaFX property triplet the documentation belongs only on the property accessor, because the standard doclet copies it over and the getter, setter and backing field stay comment free. Methods annotated with Override inherit their documentation and need a comment only when the behaviour deviates. Every package has a package-info.java with a short summary.

The demo module is exempt from the missing check, since the demo applications are not part of the published API. You can run the same check locally and see the warnings.

# generates the aggregated Javadoc and prints all DocLint warnings
./mvnw -B package -pl gemsfx

AtlantaFX support exposes how the controls are styled

The controls ship with their own user agent stylesheets, and those stylesheets are based on the CSS variables of the standard JavaFX theme, Modena. That single design decision explains both the look of the library and its one real integration constraint.

When an application switches to an AtlantaFX theme, the application's own components change but the GemsFX controls would keep their Modena appearance, which is exactly the mismatch the library tries to prevent. The readme introduces a companion stylesheet for exactly this case, and the section is cut off mid sentence in the copy available here, so the precise mechanism is not documented in the text available.

Even so, the shape of the problem is clear enough to plan around. A GemsFX control derives its appearance from the standard theme's CSS variables, so an application with a heavily customised visual identity will find that the controls either follow the theme or need the companion stylesheet applied on top. That is a different contract from a component library that accepts arbitrary CSS, and it is worth checking with a screenshot of your own theme before committing.

The alternative to GemsFX is to build the controls yourself on top of the standard JavaFX set. That gives you total control of the look and no dependency, but it also means every calendar picker, paging grid and chip input is your code to write, test and document, which is precisely the work GemsFX has already done for around 60 controls.

Apache-2.0, frequent releases and a maintenance record you can check

The licence is Apache-2.0, which is the permissive choice with an explicit patent grant, and the library is on Maven Central so it can be consumed as an ordinary dependency.

Activity is visible and recent. The repository is not archived, the last push was on 2026-10-04, and the release history shows v4.5.0 on 2026-09-21, v4.4.5 on 2026-09-03 and v4.4.4 on 2026-08-27. Three releases in under a month is the pattern of a library that is being maintained rather than parked, and the patch level in the version numbers suggests fixes are shipped between features.

The repository layout backs that up. Alongside the three Maven modules there is a docs directory for the manuals, a .jdeploy directory for the demo launcher, a .mvn directory and the mvnw wrapper scripts so that builds use a pinned Maven. jreleaser.yml drives the release process, qodana.yaml points at static analysis, and settings.xml is present for repository configuration.

Two small operational notes. The unit tests need a JavaFX toolkit, so a headless CI worker requires the Monocle properties the project already sets. And because DocLint runs on the library module, any change you make to a public API in a fork needs matching documentation, which is a useful discipline to inherit and an annoying one to retrofit.

Editorial conclusion

GemsFX suits JavaFX teams that need controls the platform does not ship, such as a calendar picker, a searchable table or a paging grid, and that want each one documented to a standard they can check in CI. It is a poor fit if your application targets a JavaFX version below 17, if you want full control of the visual design rather than a look derived from the standard theme, or if you cannot accept a third party dependency of this size. Check first that the control you need is in the list rather than a near miss, that the demo application runs on your JDK, and that the DocLint rules in the root pom.xml pass for your own patches.

Frequently asked questions

Official sources

1. dlsc-software-consulting-gmbh/GemsFX on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases