Mastering macOS Native UI in Java Swing

When developing desktop applications in Java for macOS, achieving a modern, native Look and Feel is crucial for user experience. Java provides several apple.awt properties—both system properties and Swing client properties—that let developers tweak window decorations, title bars, menu bars, and rendering options on macOS.

However, finding a single, consolidated list of these properties can be challenging because many were introduced in legacy Apple JDKs and are now maintained inside OpenJDK's Aqua Look and Feel source code.

Essential apple.awt System Properties

System properties are global configurations set via System.setProperty() or passed via command line JVM arguments (-Dproperty=value) before initializing UI components.

  • apple.laf.useScreenMenuBar (boolean): Moves the Swing JMenuBar to the top macOS screen menu bar.
  • apple.awt.application.name (string): Sets the application name displayed in the macOS menu bar.
  • apple.awt.application.appearance (string): Controls dark/light mode appearance in modern OpenJDK builds (e.g., system, NSAppearanceNameAqua, or NSAppearanceNameDarkAqua).
  • apple.awt.antialiasing (string/boolean): Enables text antialiasing for AWT/Swing rendering (e.g., on).
  • apple.awt.fractionalmetrics (string/boolean): Enables fractional font metrics for smoother text layout.

Key apple.awt Client Properties for Windows

Client properties are applied to specific JRootPane or component instances using rootPane.putClientProperty("key", value).

  • apple.awt.fullWindowContent (boolean): Extends the window content view to fill the entire window frame, including behind the title bar.
  • apple.awt.transparentTitleBar (boolean): Makes the title bar translucent or transparent, blending it seamlessly into the window background.
  • apple.awt.windowTitleVisible (boolean): Shows or hides the title text while retaining standard window controls (close, minimize, maximize).
  • apple.awt.brushMetalLook (boolean): (Legacy) Applies the classic macOS textured metal look to frames.
  • apple.awt.draggableWindowBackground (boolean): Allows dragging the window by clicking and holding any empty space inside the window content.

Code Example: Creating a Modern macOS Window

Here is how you can use these properties together in a Java Swing application:

import javax.swing.*;
import java.awt.*;

public class MacUIExample {
    public static void main(String[] args) {
        // Configure System Properties before creating UI components
        System.setProperty("apple.laf.useScreenMenuBar", "true");
        System.setProperty("apple.awt.application.name", "My Mac App");

        SwingUtilities.invokeLater(() -> {
            JFrame frame = new JFrame("Modern Mac Window");
            frame.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
            frame.setSize(800, 600);

            // Configure Client Properties on the RootPane
            JRootPane rootPane = frame.getRootPane();
            rootPane.putClientProperty("apple.awt.fullWindowContent", true);
            rootPane.putClientProperty("apple.awt.transparentTitleBar", true);
            rootPane.putClientProperty("apple.awt.windowTitleVisible", false);

            frame.setLocationRelativeTo(null);
            frame.setVisible(true);
        });
    }
}

Where to Find All apple.awt Properties

Because official Apple documentation for Java UI properties was archived after Apple handed Java development over to OpenJDK, the most accurate sources for finding all supported properties are:

  • OpenJDK Source Code: Inspect the OpenJDK repository under src/java.desktop/macosx/classes/sun/lwawt/macosx/ and com.apple.laf package classes such as AquaLookAndFeel.java and CPlatformWindow.java.
  • FlatLaf & Modern Swing Frameworks: Modern Look and Feel libraries like FlatLaf provide built-in support and comprehensive documentation for native macOS window decorations.
  • Apple Developer Legacy Archives: Historical Apple developer reference guides still provide details on legacy properties.