CalendarFX: calendar views for JavaFX without rebuilding them

What the framework actually gives you

CalendarFX is a Java framework for creating sophisticated calendar views based on JavaFX, and a detailed developer manual is published online. The views it provides are the ones every calendar product ends up needing and none wants to build: a day view, a week view, a month view and a year view, plus more specialised ones for appointments, resource booking, scheduling and a month sheet. The JavaFX choice is the defining constraint. JavaFX gives you a retained scene graph, a styling layer and a controls library that a desktop application can make consistent, and CalendarFX builds on those rather than trying to be a general purpose UI toolkit. The library is on Maven Central under the coordinates com.calendarfx:view, so adding a calendar to an existing JavaFX application is a dependency declaration rather than a project.

One module ships, the rest are samples

The module list is the clearest statement of the project's design. CalendarFXView is the main module containing the various calendar views. Everything else is a demo application: CalendarFXSampler, a demo app based on FXSampler to test controls individually, CalendarFXApp for the day, week, month and year views, CalendarFXAppointmentsApp for the appointments view, CalendarFXiCal for working with iCalendar data, CalendarFXGoogle for working with Google calendars, CalendarFXResourceApp for the resource calendar view, CalendarFXSchedulerApp for the scheduler view, and CalendarFXWeather for the month sheet view. Only CalendarFXView is published. The demo modules are built through the all-modules Maven profile, which is active unless -Drelease=true is passed, so the release build excludes them while a normal developer build compiles everything.

The dependency and the runtime floors

The Maven coordinates are ordinary.

<dependency>
    <groupId>com.calendarfx</groupId>
    <artifactId>view</artifactId>
    <version>12.1.2</version>
</dependency>

The runtime requirements are stated plainly: CalendarFX requires Java 21 or later and JavaFX 23 or later. That is a demanding floor, and it is worth checking before you plan around the library, because JavaFX 23 is recent and the Java 21 requirement means the application cannot be built for an older runtime. The version numbers move in a two-part scheme, with 12.1.2 and 12.1.0 as the recent releases and 12.2.0 following, which suggests a stable major line with frequent patches rather than frequent breaking changes.

Running and building locally

Running a demo is one Maven goal from the module folder of the corresponding app.

mvn javafx:run

For a local install, so the library can be used as a dependency in other projects on the same machine, there is the wrapper.

./mvnw install

And to run the tests of the library module alone, without the demo applications, the wrapper targets a single module.

./mvnw -pl CalendarFXView test

The split between those two commands is the practical workflow. The demos are there to try controls in isolation, which is what the FXSampler-based module is for, and the library test suite is what you run before a change.

AtlantaFX theming and the system property

The theming support is the one piece of configuration that is not obvious. To use AtlantaFX you need to pass a system property to your application.

-Datlantafx=true

Or set it from inside the application.

System.setProperty("atlantafx", "true");

Doing so makes the controls inside CalendarFX always use the atlantafx.css file instead of the default calendar.css file. The last step is to set one of the AtlantaFX themes as the default theme for your application, for example by calling Application.setUserAgentStylesheet with the user agent stylesheet from a theme such as NordDark. Obviously all of this requires the AtlantaFX library on your classpath. The design point is that the switch is a property rather than a constructor argument, so a library that embeds CalendarFX can enable the theme without the application having to thread a flag through every call site.

What else is in the repository

The root listing shows the project infrastructure, which is standard for a Java library with a release process. There is a pom.xml and the Maven wrapper scripts mvnw and mvnw.cmd, plus a.mvn directory. The release is configured through jreleaser.yml, which is the tool that publishes to Maven Central and handles the staging repository, and settings.xml holds the repository configuration. There is a formatter-settings.xml, and a scenicView.properties configuration file. The CI setup includes a build workflow and a CodeQL workflow, so there is automated static analysis on top of the build. Documentation lives in a docs directory, CHANGES.txt records notable changes, and the security, code of conduct and contributing documents are present, with the README asking for vulnerabilities to be reported privately rather than through the issue tracker.

Where CalendarFX is the wrong choice

Four limits apply. It is a desktop framework for JavaFX, so it does nothing for a browser, a mobile application or a server-side rendering of a calendar, and the Java 21 and JavaFX 23 floor means it cannot be used in the long-lived enterprise deployments that are still on older runtimes. Only the view module is published, so the appointments, scheduler, resource, iCalendar and Google integrations are samples you read rather than components you depend on, and if you need one of them in production you are reading the code and writing the integration yourself. The theming model is prescriptive in the sense that AtlantaFX changes which stylesheet the controls use, so an application with its own stylesheet has to reconcile the two rather than layer them. And a project with a modest commercial relationship around it, since commercial support and custom development is offered by the consulting company behind it, means the open source version is the community edition of a product rather than a purely community project.

Editorial conclusion

Use CalendarFX when you are putting a calendar into a JavaFX desktop application and the day, week, month and year views would otherwise be weeks of work, because the framework ships those views with selection, navigation and entry support already worked out. Do not reach for it if your product is web based, since the whole thing is JavaFX and there is no browser target. Verify first that your application is on Java 21 and JavaFX 23, that you can live with the theme model, since switching to AtlantaFX means the controls always use atlantafx.css rather than the default calendar.css, and how much of the framework you need, because the appointment, scheduler, resource, iCalendar and Google modules are demo applications rather than published library modules.

Frequently asked questions

Official sources

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