Liquid Glass and VAqua

In macOS 26 (Tahoe), Apple introduced a new UI they call Liquid Glass. VAqua 14 adds limited support for the new UI. The limitations are described below.

The new UI has important implications for developers of applications that use VAqua:

• Significant effort may be required to enable the new UI.
• Because of AppKit bugs, use of the new UI in production applications on macOS 26 may be undesirable. (Most of the bugs appear to be fixed in macOS 27.) A small application change is recommended to ensure that the new UI is not used when running on macOS 26.
• Use of the new UI will probably require some changes to applications.

Enabling the new UI

Apple supports a transition period for developers to convert their applications to use the new UI; however, their approach does not work well for Java applications. To use the new UI, a Java application must use a Java runtime that was built using Xcode 26 or later. Until JDK vendors provide a JDK that was built using Xcode 26 or later, it may be necessary to build your own JDK.

An alternative is to use the custom jpackage launcher available here when building a bundled application. (Note that only an updated JDK will enable the new UI when an IDE runs your application using a JDK.)

AppKit bugs

AppKit on macOS 26 contains several rendering bugs that affect VAqua. Specifically, these bugs impact the rendering of large buttons with rounded corners (high contrast mode only) and editable combo boxes (small and mini in all modes, regular and larger only in high contrast mode). To ensure that the new UI is not used on macOS 26, using any current or future JDK, add this Info.plist entry to your application:

UIDesignRequiresCompatibility = YES

This property only affects applications running on macOS 26. See documentation.

Application changes

When the Liquid Glass UI is used, many components that previously had rectangular borders are changed to have rounded corners. In addition, many toolbar components are significantly larger. Adapting to these changes may require changes to the UI layout.

New Features

VAqua supports some new features when the Liquid Glass UI is enabled.

Sliders using the new UI support a neutral value. When the slider value equals the neutral value, no highlight is painted. Otherwise, the highlight is painted between the neutral value and the actual value. The neutral value is specified by setting the client property Aqua.sliderNeutralValue. If this client property is not set, the original display style is used.

A new button style glass has been added.

Limitations

VAqua support for the Liquid Glass UI has limitations.

• All glass effects are simulated, either by native code or by VAqua.
• The navigation view window style is not supported.
• The expanding toolbar search field is not supported.
• Toolbar button rendering is somewhat different than native toolbars.
• The liquid glass slider thumb is not supported.