PreferencesFX turns JavaFX property beans into a preferences dialog

The problem is layout code, not logic

The stated problem is narrow and specific: creating preference dialogs in JavaFX is a tedious and very error-prone task, and PreferencesFX is a framework that solves it. The framework enables a developer to create preference dialogs with ease and creates well designed and user friendly preference dialogs by default.

That framing matters because it is not a general purpose UI toolkit. Nothing here helps you build a chart or a table. The entire value proposition sits in one screen of an application, the one where a user changes how the application behaves.

The stated advantages are less error prone, less code needed, easy to learn, easy to understand, and easy to use for developers and users alike. The first of those is the interesting claim. A preferences panel is a grid of labels and controls, and hand writing one is mostly layout work, but the reason it is error prone is that the bidirectional bindings between the controls and the underlying settings have to be wired up consistently by hand, and a missed binding is a setting that silently does not work.

The library is licensed Apache-2.0, published under the group id com.dlsc.preferencesfx with the artifact preferencesfx-core, and it is listed on Maven Central and on JFXCentral. The repository's default branch is master-11, which reflects that the project tracks JavaFX versions in parallel.

Categories, groups and settings form a fixed hierarchy

The structure is the API. A preferences dialog can contain multiple Categories, each Category contains one or more Groups, and each Group contains one or more Settings.

The construction call shows the shape of it:

PreferencesFx preferencesFx = 
    PreferencesFx.of(SaveClass.class,
        Category.of("Category Title",
            Group.of("Group Title",
                Setting.of("Setting Title", new Property())
            )
        )
    );

The first argument is the save class, used to reference the saved values of settings to it. The library builds the tree from the inside out, and the developer only supplies titles and properties.

The notes around that snippet describe how much flexibility the model actually gives you. It is possible to omit the Group and declare all settings in a Category directly, in which case the settings are simply displayed one after another without grouping. A Group can also be defined without a title, in which case the individual groups are displayed with more space in between so they can be told apart. A Category can take a graphic node to use as an icon as its second argument, for example an ImageView wrapping an Image loaded from a file path.

So the hierarchy is a convention with escape hatches rather than a rigid schema, and the escape hatches are the cases where a developer wants a layout the default does not give.

Settings bind to the JavaFX properties you already have

The settings themselves are ordinary JavaFX properties. The documentation's own example declares them first:

StringProperty stringProperty = new SimpleStringProperty("String");
BooleanProperty booleanProperty = new SimpleBooleanProperty(true);
IntegerProperty integerProperty = new SimpleIntegerProperty(12);
DoubleProperty doubleProperty = new SimpleDoubleProperty(6.5);

and then wraps them in Setting.of calls inside categories. The documentation also lists pre-defined setting types, including Integer, Double, Boolean, String, Lists and Objects, so the type is inferred from the property rather than declared.

The architectural consequence is significant. PreferencesFX does not own your settings model; it renders it. That is why the save class exists: the framework needs a stable anchor to store values against, and the property itself remains the live source of truth in your code.

This also explains the instant persistence feature in the feature table, where any changes to the application are saved instantly. There is no apply button in the model because there is no staging layer in the model. The feature table separately describes the cancel button as discarding all changes made during the time the dialog was last opened, and the close button as simply closing the window and leaving the preferences as they are. Those two behave differently, and the difference is worth understanding before you wire a cancel button into a flow that has already written to disk.

Search, tree view, breadcrumbs and undo are what the panel adds

Beyond assembling controls, the framework contributes a set of behaviours that would otherwise be a lot of work.

Search and filter filters all categories for a given string and lets a user find a Setting, Group or Category by name. The tree view shows all categories in a hierarchical structure. The breadcrumb bar shows the user the previous categories in the hierarchy leading to the currently displayed category and lets them navigate back. Undo and redo buttons allow a stepwise undo and redo of the last changes.

The tree view and breadcrumb bar are not unconditional. The OneCategory demo exists specifically to show the behaviour of the API when only one category is used, and in that case the breadcrumb bar and tree view are omitted from the GUI.

That is a sensible design decision and also a hint about the intended scale of a preferences screen. The Extended demo is described as populated with lots of categories, groups and settings without any bindings, designed to show usage in a big project, which suggests the framework expects a preferences dialog with real depth rather than three checkboxes. The Standard demo is the opposite case, with a few settings and fully working bindings.

A related point is that the framework supplies the entire visual design. There is no theming layer described, no skinning hook, and no documented way to restyle the panel to match an existing application. That is the trade you accept for the convenience.

Adding it to a Maven or Gradle build

The distribution story is plain. The project publishes an artifact for JavaFX applications, and the documentation gives a dependency block per Java version. For a Maven build with Java 8:

<dependency>
  <groupId>com.dlsc.preferencesfx</groupId>
  <artifactId>preferencesfx-core</artifactId>
  <version>8.6.0</version>
</dependency>

and for Java 11:

<dependency>
  <groupId>com.dlsc.preferencesfx</groupId>
  <artifactId>preferencesfx-core</artifactId>
  <version>11.8.0</version>
</dependency>

Gradle builds get the equivalent definitions, one per Java line:

dependencies {
    compile group: 'com.dlsc.preferencesfx', name: 'preferencesfx-core', version: '11.8.0'
}

Two practical notes on those snippets. The Gradle examples use the older compile configuration rather than implementation, so you may need to adjust the configuration name for a current Gradle setup. And the versions quoted in the documentation are not the newest: the most recent release is v11.19.0, while the dependency snippets point at 11.8.0 for Java 11 and 8.6.0 for Java 8, which is a sign the build instructions lag the release history.

The repository itself is a Maven project with a mvnw wrapper alongside mvnw.cmd, a settings.xml, a jreleaser.yml for release automation, a CHANGELOG.md and two modules, preferencesfx and preferencesfx-demo.

Demos, localisation and validation are documented features

Four demos ship in the repository and they double as documentation of the API's behaviour. Standard shows a few settings with working bindings. Internationalized shows how to define preference dialogs in multiple languages using internationalization. OneCategory covers the single category case described earlier, where the breadcrumb bar and tree view are dropped. Extended is the large project case without bindings.

To run them, launch the demo starter class in the preferencesfx-demo module and look at the different tabs. That is the fastest way to decide whether the default look of the panel suits your application before you commit to it.

The documentation itself is generated. The project uses the asciidoctor plugin, and the generated output lands in a target/generated-docs subdirectory after a Maven task runs:

process-resources

Two more capabilities are listed as sections of the documentation rather than demonstrated in the README: localisation and validation. The Internationalized demo confirms the localisation path exists. Validation, in the sense of rejecting a bad value before it is stored, is a feature a developer would want in a settings panel, but the README does not describe its API, so it would have to be read in the generated docs.

One more file is worth knowing about. The top level includes a CHANGELOG.md and a jreleaser.yml, so releases are automated and versioned, but there is no top level licence summary beyond the Apache-2.0 marker on the project itself.

Where the framework is the wrong choice

The constraints are real and they follow directly from the design.

The first is platform. This is a JavaFX framework. An application that also ships on the web or on Android cannot use it, and a Swing application cannot use it either, since the settings types are JavaFX properties and the widgets are JavaFX nodes. Adopting it means committing the settings screen of your desktop application to JavaFX permanently.

The second is styling. The framework produces a panel with a specific look, a tree view, a breadcrumb bar and a search field. There is no documented theming mechanism, so an application with a carefully designed settings screen, or with a company design system, cannot have both. You would be accepting the framework's appearance to get its behaviour.

The third is persistence timing. Because changes are saved instantly, a cancel button has to actively undo work already written. The feature table describes cancel as discarding changes made during the time the dialog was last opened, but the mechanism is not documented, and for settings that trigger expensive side effects, instant persistence with a compensating undo is a harder contract than save on apply.

The fourth is the maintenance picture. The last push was on 2026-04-10 and the most recent release is v11.19.0, from the same day. Previous releases came at v11.17.0 in January 2024 and v11.16.0 in May 2023, so the cadence was already irregular, and there has been no recorded change for over six months. That is not disqualifying for a stable UI component, but it is a fact to weigh against a library that ships on a schedule.

Finally, the documentation is thin in exactly the place a developer needs it most. The README shows the constructor and the property types, but says nothing about the validation API, the localisation mechanism, or how the persisted values are keyed and stored, so you would be reading generated docs and source to answer basic questions.

Editorial conclusion

PreferencesFX fits a JavaFX desktop application that already keeps its settings in JavaFX properties and wants a presentable preferences panel without hand writing layout, search and undo. It is the wrong choice for a Swing application, for a multi platform app that will also run on the web or on mobile, or for a team that needs a settings screen matching an existing design system, because the framework supplies its own look and its own persistence. Before adopting it, check three things: the JavaFX version your application targets against the 8.6.0 and 11.8.0 lines named in the documentation, the persistence model, since changes are saved instantly rather than on an explicit apply, and the maintenance picture, because the last push was on 2026-04-10 and the most recent release is v11.19.0, which means you would be depending on a project whose recent activity is over six months old.

Frequently asked questions

Official sources

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