AtlantaFX Review: JavaFX Themes, Controls, and Extensions

Why AtlantaFX targets conventional JavaFX applications

AtlantaFX addresses a specific gap between JavaFX's built-in control set and applications that need a more contemporary visual system without replacing the standard programming model. The project describes itself as a JavaFX CSS theme collection with additional controls. Its intended users are JavaFX developers working on desktop interfaces where consistent light and dark themes, reusable styling, and application-specific visual details matter.

The central design choice is compatibility with existing JavaFX controls. AtlantaFX starts with CSS and adds a separate set of controls rather than requiring an application to adopt a new application framework. That makes it more approachable for teams with standard JavaFX scenes, Scene Builder documents, or custom layouts. The README also lists a fluent validation API, custom window decorations, loading indicators, a sampler application, and a Scene Builder integration, giving the project a wider scope than a standalone stylesheet archive.

The project is not trying to become a general-purpose controls library. Its contribution guide explicitly says that creating another controls library is not the main goal. This boundary matters. Teams can use the themes with ordinary controls, while the additional controls address selected modern interface needs without requiring wholesale replacement of JavaFX.

How the CSS-first theming and control architecture fits together

AtlantaFX is organized around modular SASS sources. The README describes this as an alternative to searching through thousands of generated CSS lines, and it identifies a simple color system with global accent colors and individual looked-up color variables. That gives applications two likely levels of customization: change the accent used by a theme, or override the appearance of a particular control.

At runtime, a theme supplies a JavaFX user-agent stylesheet. The documented basic path calls `Application.setUserAgentStylesheet(...)` with a theme object, while `ThemeManager` can select the default theme or set one manually. The README also documents platform color-scheme selection through `ThemeManager.useDefault()`, and a Java property named `-Datlantafx.theme` can be used to select a theme by name.

This architecture separates visual policy from individual control classes. Standard controls can receive theme styling through CSS, while additional AtlantaFX controls and skins supply more specialized behavior. The validation module is described as a fluent API for JavaFX applications, and the decorations module addresses controls placed in a title bar. The sampler application can preview themes, inspect control examples, change palette contrast, and hot reload styles without restarting the entire app. That sampler is useful during design work because it turns CSS customization into an iterative visual process.

Installing atlantafx-base 3.0.0 with Maven or Gradle

The documented runtime requirement is Java 25 or later and JavaFX 27 or later. For Maven, add `atlantafx-base` version `3.0.0` to the project dependencies. The dependency coordinates in the README are exact, so the first compatibility decision is whether the target application can move to these platform versions.

The following Maven declaration adds the base theme and controls module:

<dependency>
    <groupId>io.github.mkpaz</groupId>
    <artifactId>atlantafx-base</artifactId>
    <version>3.0.0</version>
</dependency>

For Gradle, enable `mavenCentral()` and add the same implementation dependency:

repositories {
    mavenCentral()
}

dependencies {
    implementation 'io.github.mkpaz:atlantafx-base:3.0.0'
}

The first real use is to set a theme before creating the application's visual content. The README gives this Java example, which uses `PrimerLight` and applies its user-agent stylesheet:

public class Launcher extends Application {
    @Override
    public void start(Stage stage) {
        Application.setUserAgentStylesheet(new PrimerLight().getUserAgentStylesheet());
    }
}

The `main` method and the rest of the application are omitted in the README's abbreviated example. A complete launcher still needs to call `launch(args)`, and the project documentation should be consulted for the imports and the surrounding application setup.

Using ThemeManager and packaged CSS without the Maven dependency

AtlantaFX offers a second integration path through `ThemeManager`. `ThemeManager.useDefault()` selects a theme based on the platform color-scheme preference, or a theme named through Java properties when the application is run with `-Datlantafx.theme=name`. A specific theme can also be assigned with `ThemeManager.instance().setTheme(...)`.

This is useful when theme selection is an application setting rather than a hard-coded design decision. The README does not enumerate every available theme name in the displayed getting-started section, so an application should use the themes found in the `atlantafx.base.theme` package and avoid assuming a name that is not documented there.

Teams that do not want additional dependencies can download compiled CSS themes from GitHub Releases. The README says to unpack `AtlantaFX-*-themes.zip` and place the files on the project's classpath. The stylesheet URI can then be passed to JavaFX, or the URI can be supplied through the `javafx.userAgentStylesheetUrl` Java property:

// specify the theme stylesheet URI directly:
Application.setUserAgentStylesheet(URI);

// ... or use a Java property:
-Djavafx.userAgentStylesheetUrl=[URI]

The release archive path offers fewer library conveniences than `atlantafx-base`, and the README does not state that every additional control is included in this CSS-only route. It is primarily a way to use compiled theme resources.

The sampler, Scene Builder, decorations, and validation surfaces

The repository layout shows that AtlantaFX is split across focused modules rather than one generic package. `base/` contains the base controls and themes, `styles/` covers theming and styles, `decorations/` handles window decorations, `validation/` contains validation support, `scene-builder/` contains the integration, `sampler/` contains the demo application, and `spins/` contains custom loading indicators.

This separation can help an application adopt only the parts it needs. A project may use the CSS themes without adopting validation or title-bar controls. Another may use the validation API alongside existing forms. The Scene Builder integration is relevant for teams whose UI construction happens in the visual designer, while the sampler provides a place to inspect supported themes and control examples.

There is also a custom-theme route. The README links to `mkpaz/atlantafx-sample-theme` for compiling a custom theme from the existing SASS sources. That is useful when an organization needs a branded accent color or a maintained visual variant, but it introduces a build-time styling responsibility rather than simply selecting a packaged theme. The displayed README does not provide a complete custom-theme tutorial, so teams should consult the linked sample and the module documentation before assuming that a Java-level property is sufficient.

Compatibility, maintenance, and the limits of the CSS-first approach

AtlantaFX has a clear platform constraint: Java 25+ and JavaFX 27+ for the current documented setup. It should not be treated as a drop-in library for applications that must continue compiling against an older Java or JavaFX baseline. That requirement affects the JDK used to build, the runtime used to launch, and potentially the deployment policy of the desktop application.

The repository is not archived, and its last push was on 2026-09-28. The latest listed release is `v3.0.0`, dated 2026-09-24, following `v2.1.0` from 2025-07-11 and `v2.0.1` from 2023-06-17. Those dates show recent release activity, but they do not remove the need to check JavaFX behavior for the controls and layouts used by the application. The README directs suspected problems that are not related to CSS or a custom AtlantaFX control to the OpenJFX bug tracker, which indicates that AtlantaFX sits on top of JavaFX rather than replacing its control implementation.

The license is MIT. That provides the project's stated licensing basis for reuse and modification, subject to the license text and applicable notices. This review does not provide legal advice, and applications should preserve required copyright and license notices when redistributing artifacts.

The main limitation is scope. AtlantaFX is primarily a CSS theme library, and its controls and skins are expected to grow gradually. A team seeking a complete replacement for JavaFX, or a project that needs a large catalog of specialized controls with no styling work, may find the library too focused. The README does not document a rollback procedure, so upgrades should be evaluated against the application's controls, Scene Builder documents, validation flows, and platform runtime.

Editorial conclusion

AtlantaFX is suitable for new JavaFX applications that can adopt Java 25, JavaFX 27, and a CSS-first presentation layer, especially when validation, decorations, or Scene Builder support are part of the requirements. It is a poor fit for an older JavaFX baseline, an application that must remain limited to standard controls, or a team that does not want to own custom skins and styling compatibility. Before adoption, verify that the required JavaFX 27 baseline matches the deployment environment, then inspect how the additional controls behave with the application layouts and themes it already uses.

Frequently asked questions

Official sources

1. License: MIT
2. mkpaz/atlantafx on GitHub
3. Project website
4. README
5. Releases