🛠️ Compose Native Tray

📖 Introduction

Compose Native Tray is a modern Kotlin library for creating applications with system tray icons, offering native support for Linux, Windows, and macOS. It uses an intuitive Kotlin DSL syntax and fixes issues with the standard Compose for Desktop solution.

✨ Features

Cross-platform support for Linux, Windows, and macOS.
DSL-style syntax to define tray menus with ease.
Supports standard items, submenus, dividers, and checkable items.
Ability to enable/disable menu items dynamically.
Corrects issues with the Compose for Desktop tray, particularly HDPI support on Windows and Linux.
Improves the appearance of the tray on Linux, which previously resembled Windows 95.
Adds support for checkable items, dividers, and submenus, including nested submenus.
Supports primary action for Windows, macOS, and Linux.
- On Windows and macOS, the primary action is triggered by a left-click on the tray icon.
- On Linux, on GNOME the primary action is triggered by a double left-click on the tray icon, while on the majority of other environments, primarily KDE Plasma, it is triggered by a single left-click, similar to Windows and macOS.
Single Instance Management: Ensures that only one instance of the application can run at a time and allows restoring focus to the running instance when another instance is attempted.
Tray Position Detection: Allows determining the position of the system tray, which helps in positioning related windows appropriately.
Compose Recomposition Support: The tray supports Compose recomposition, making it possible to dynamically show or hide the tray icon, for example:

🎯 Why Compose Native Tray?

This library was created to solve several limitations of the standard Compose for Desktop solution:

✅ Improved HDPI support on Windows and Linux
✅ Modern appearance on Linux (no more Windows 95 look!)
✅ Extended features: checkable items, nested submenus, separators
✅ Native primary action: left-click on Windows/macOS, single-click (KDE) or double-click (GNOME) on Linux
✅ Full Compose recomposition support: fully reactive icon and menu, allowing dynamic updates of items, their states, and visibility

📸 Preview

Windows	macOS
Ubuntu GNOME	Ubuntu KDE

⚡ Installation

Add the dependency to your build.gradle.kts:

dependencies {
  // System tray icon + menu (lightweight — no windowing backend pulled in)
  implementation("dev.nucleusframework:composenativetray:<version>")

  // Only if you use TrayApp (the tray + anchored popup window API).
  // Pulls in the Nucleus application / decorated-window-tao backend.
  implementation("dev.nucleusframework:composenativetray-app:<version>")
}

Since 2.1.0 the library is split in two so apps that only need a tray icon don't pull in the heavier decorated-window-tao windowing backend (see #418). Tray and the menu DSL live in composenativetray and work in any Compose Desktop application { } — no Nucleus application scope required. TrayApp lives in composenativetray-app and needs nucleusApplication { }. Add the second artifact only when you use TrayApp.

🚀 Quick Start

Minimal example to create a system tray icon with menu. Tray is a regular composable — it works inside Compose Desktop's application { … } or Nucleus' nucleusApplication { … }:

application {
  Tray(
    icon = Icons.Default.Favorite,
    tooltip = "My Application"
  ) {
    Item(label = "Settings") {
      println("Settings opened")
    }
    
    Divider()
    
    Item(label = "Exit") {
      exitProcess(0)
    }
  }
}

💡 Recommendation: It is highly recommended to check out the demo examples in the project's demo directory. These examples showcase various implementation patterns and features that will help you better understand how to use the library effectively.

Notable demos:

DemoWithDrawableResources.kt – shows using DrawableResource directly for Tray and menu icons

DemoWithPainter.kt – demonstrates using a painterResource icon

DemoWithoutContextMenu.kt – minimalist tray with primary action only

TrayAppDemo.kt – the full TrayApp (tray + popup window) example

📚 Usage Guide

🎨 Creating the System Tray Icon

New: Using a DrawableResource directly

Tray(
  icon = Res.drawable.myIcon,  // org.jetbrains.compose.resources.DrawableResource
  tooltip = "My Application"
) { /* menu */ }

Requires compose.components.resources in your project. In this library it's already included; in your app add: implementation(compose.components.resources)

Option 1: Using an ImageVector

Tray(
  icon = Icons.Default.Favorite,
  tint = null,  // Optional: if null, the tint automatically adapts (white in dark mode, black in light mode) according to the isMenuBarInDarkMode() API
  tooltip = "My Application"
) { /* menu */ }

Option 2: Using a Painter

Tray(
  icon = painterResource(Res.drawable.myIcon),
  tooltip = "My Application"
) { /* menu */ }

Option 3: Using a Custom Composable

Tray(
  iconContent = {
    Canvas(modifier = Modifier.fillMaxSize()) { // Important to use fillMaxSize()!
      // A simple red circle as an icon
      drawCircle(
        color = Color.Red,
        radius = size.minDimension / 2,
        center = center
      )
    }
  },
  tooltip = "My Application"
) { /* menu */ }

⚠️ Important: Always use Modifier.fillMaxSize() with iconContent for proper icon rendering.

Option 4: Platform-Specific Icons

This approach allows respecting the design conventions of each platform:

Windows: Traditionally uses colored icons in the system tray
macOS/Linux: Prefer monochrome icons that automatically adapt to the theme

val windowsIcon = painterResource(Res.drawable.myIcon)
val macLinuxIcon = Icons.Default.Favorite

Tray(
  windowsIcon = windowsIcon,      // Windows: full colored icon
  macLinuxIcon = macLinuxIcon,    // macOS/Linux: adaptive icon
  tooltip = "My Application"
) { /* menu */ }

💡 Note: If no tint is specified, ImageVectors are automatically tinted white (dark mode) or black (light mode) based on the theme.

🖱️ Primary Action

Define an action for clicking on the icon. The behavior varies by platform:

Windows/macOS: Left-click on the icon (native implementation for macOS)
Linux: Single-click on KDE or double-click on GNOME (implementation via DBus)

Tray(
  icon = Icons.Default.Favorite,
  tooltip = "My Application",
  primaryAction = {
    println("Icon clicked!")
    // Open a window, display a menu, etc.
  }
) { /* menu */ }

📋 Building the Menu

Important note: It's not mandatory to create a context menu. You can use only an icon in the tray with a primary action (left-click) to restore your application, as shown in the DemoWithoutContextMenu.kt example. This minimalist approach is perfect for simple applications that only need a restore function.

The menu uses an intuitive DSL syntax with several types of elements:

Tray(/* configuration */) {
  // Simple item with icon
  Item(label = "Open", icon = Icons.Default.OpenInNew) {
    // Click action
  }
  
  // Item with custom icon via iconContent
  Item(
    label = "Custom",
    iconContent = {
      Icon(
        Icons.Default.Star,
        contentDescription = null,
        tint = Color.Yellow,
        modifier = Modifier.fillMaxSize() // Important!
      )
    }
  ) { }
  
  // Checkable item
  CheckableItem(
    label = "Dark Mode",
    icon = Icons.Default.DarkMode,
    checked = isDarkMode,
    onCheckedChange = { isDarkMode = it }
  )
  
  // Submenu
  SubMenu(label = "Options", icon = Icons.Default.Settings) {
    Item(label = "Option 1") { }
    Item(label = "Option 2") { }
    
    // Nested submenus supported!
    SubMenu(label = "Advanced") {
      Item(label = "Advanced Option") { }
    }
  }
  
  // Visual separator
  Divider()
  
  // Disabled item - the isEnabled property controls whether the item can be clicked
  Item(label = "Version 1.0.0", isEnabled = false)
  
  // Enabled item (isEnabled is true by default)
  Item(label = "Help", isEnabled = true) {
    // This action will be executed when clicked
  }
  
  // Exit properly
  Item(label = "Exit") {
    dispose()  // Removes the system tray icon
    exitProcess(0)
  }
}

Icons with painterResource

New: Icons with DrawableResource in menu items

You can now pass DrawableResource directly to menu builders:

Tray(icon = Res.drawable.app_icon, tooltip = "App") {
  SubMenu(label = "With icons", icon = Res.drawable.gear) {
    Item(label = "Action 1", icon = Res.drawable.star) { /* ... */ }
    Item(label = "Action 2", icon = Res.drawable.star) { /* ... */ }
  }

  Divider()

  CheckableItem(
    label = "Enabled",
    icon = Res.drawable.check,
    checked = true,
    onCheckedChange = { /* ... */ }
  )
}

See demo/DemoWithDrawableResources.kt for a complete example. When using painterResource with menu items, declare it in the composable context:

application {
  val advancedIcon = painterResource(Res.drawable.advanced) // ✅ Correct
  
  Tray(/* config */) {
    SubMenu(
      label = "Advanced",
      icon = advancedIcon  // Use the variable
    ) { /* items */ }
  }
}

🔧 Advanced Features

🔄 Fully Reactive System Menu

The library supports Compose recomposition for all aspects of the system menu:

// Example 1: Dynamic display/hiding of the icon
var isWindowVisible by remember { mutableStateOf(true) }

// The icon only appears when the window is hidden
if (!isWindowVisible) {
  Tray(
    icon = Icons.Default.Favorite,
    tooltip = "Click to restore"
  ) {
    Item(label = "Restore") {
      isWindowVisible = true
    }
  }
}

// Example 2: Fully reactive menu
application {
  var darkMode by remember { mutableStateOf(false) }
  var showAdvancedOptions by remember { mutableStateOf(false) }
  var notificationsEnabled by remember { mutableStateOf(true) }
  var isConfigAvailable by remember { mutableStateOf(false) }

  Tray(
    // The icon changes based on the mode
    icon = if (darkMode) Icons.Default.DarkMode else Icons.Default.LightMode,
    tooltip = "My Application"
  ) {
    // Item with reactive label and icon
    Item(
      label = if (darkMode) "Switch to Light Mode" else "Switch to Dark Mode",
      icon = if (darkMode) Icons.Default.LightMode else Icons.Default.DarkMode
    ) {
      darkMode = !darkMode
    }

    // Reactive checkable item
    CheckableItem(
      label = "Notifications",
      checked = notificationsEnabled,
      onCheckedChange = { notificationsEnabled = it }
    )

    // Conditional display of items
    if (showAdvancedOptions) {
      Divider()

      SubMenu(label = "Advanced Options") {
        // Item with dynamically changing isEnabled property
        Item(
          label = "Configuration", 
          isEnabled = isConfigAvailable
        ) { /* action */ }
        
        // This item enables the Configuration option when clicked
        Item(label = "Check Configuration Availability") { 
          isConfigAvailable = true 
        }
        
        Item(label = "Diagnostics") { /* action */ }
      }
    }

    Divider()

    // Visibility control
    Item(
      label = if (showAdvancedOptions) "Hide Advanced Options" else "Show Advanced Options"
    ) {
      showAdvancedOptions = !showAdvancedOptions
    }
  }
}

All menu properties (icon, labels, states, item visibility) are reactive and update automatically when application states change, without requiring manual recreation of the menu.

🔑 Single Instance Management

Prevent multiple instances of your application:

The single instance manager combined with the primary action (left-click) is particularly useful for restoring a minimized application in the tray rather than opening a new instance. This improves the user experience by:

Avoiding resource duplication and confusion with multiple windows
Preserving the current state of the application during restoration
Offering behavior similar to native system applications

Single instance is enabled by default in nucleusApplication; pass enableSingleInstance = false to opt out. When a second launch is detected, the already-running instance is notified through SingleInstanceRestoreEffect — restore your window (or re-open the tray popup) there instead of starting a new process:

import dev.nucleusframework.application.SingleInstanceRestoreEffect

nucleusApplication(enableSingleInstance = true) { // true is the default
  var isWindowVisible by remember { mutableStateOf(true) }

  // Runs in the already-running instance each time the app is launched again.
  SingleInstanceRestoreEffect {
    isWindowVisible = true // bring the existing window / tray popup back
  }

  // ... Tray / TrayApp / windows
}

See TrayAppDemo.kt for a working example (a second launch re-opens the tray popup).

Deep links

To react to a deep link the OS hands to the app (including one that arrives on a second launch while single instance is enabled), register a handler on the application scope:

nucleusApplication {
  onDeepLink { uri ->
    // handle the incoming URI (navigate, restore state, …)
  }

  // ... Tray / TrayApp / windows
}

📍 Position Detection

Tray positioning needs screen geometry (the Tao backend), so these helpers live in the composenativetray-app artifact (package dev.nucleusframework.composenativetray.trayapp) — the same one that provides TrayApp, which uses them internally.

getTrayPosition() tells you which screen corner the tray icon sits in:

val corner: TrayPosition = getTrayPosition() // TOP_LEFT / TOP_RIGHT / BOTTOM_LEFT / BOTTOM_RIGHT

Windows / macOS: resolved from the native tray/menu-bar region.
Linux: uses the desktop-environment convention (no reliable native tray-region API).

getTrayWindowPosition(...) computes a precise window position anchored to the tray icon:

val windowPosition = getTrayWindowPosition(windowWidth = 800, windowHeight = 600)

The window is horizontally centered on the icon and vertically anchored to the top or bottom of the screen depending on where the tray lives. For a ready-made tray + popup window, prefer TrayApp.

🌓 Dark Mode Detection

Automatically adapt your icons to the theme:

val isMenuBarDark = isMenuBarInDarkMode()

Tray(
  iconContent = {
    Icon(
      Icons.Default.Favorite,
      contentDescription = "",
      tint = if (isMenuBarDark) Color.White else Color.Black,
      modifier = Modifier.fillMaxSize()
    )
  },
  tooltip = "My Application"
) { /* menu */ }

Platform Behavior:

macOS: The menu bar depends on the wallpaper, not the system theme
Windows: Follows the system theme
Linux: GNOME/XFCE/CINNAMON/MATE always dark, KDE follows the theme

💡 macOS Note: The system tray icon follows the menu bar color (based on the wallpaper), but the menu item icons follow the system theme.

🎨 Icon Rendering Customization

Two options for customizing rendering:

// Option 1: Optimized for the current OS
Tray(
  icon = Icons.Default.Favorite,
  iconRenderProperties = IconRenderProperties.forCurrentOperatingSystem(
    sceneWidth = 192,    // Compose scene width
    sceneHeight = 192,   // Compose scene height
    density = Density(2f) // Rendering density
  )
) { /* menu */ }

// Option 2: Without forced scaling
Tray(
  icon = Icons.Default.Favorite,
  iconRenderProperties = IconRenderProperties.withoutScalingAndAliasing(
    sceneWidth = 192,
    sceneHeight = 192,
    density = Density(2f)
  )
) { /* menu */ }

By default, icons are optimized by OS: 32x32px (Windows), 44x44px (macOS), 24x24px (Linux).

⚠️ Platform-Specific Notes

Icon Limitations

GNOME: Icons don't display in submenus
Windows: Checkable items with icons don't display the check indicator

Theme Behavior

macOS: The menu bar color depends on the wallpaper, not the system theme
Windows: Follows the system theme
Linux: Varies by desktop environment (GNOME/KDE/etc.)

ProGuard / R8

When building a release package (e.g. via packageReleaseUberJarForCurrentOS), you need to add ProGuard rules to keep JNA and library classes since this library relies on reflection. Without these rules, the tray icon may render incorrectly (semi-transparent background, broken click actions, wrong tooltip).

Add the following to your ProGuard rules file:

-keep class com.sun.jna.** { *; }
-keep class dev.nucleusframework.composenativetray.** { *; }

🧪 TrayApp (Alpha)

Status: Alpha — The core API is functional on Windows, macOS, and Linux, but breaking changes may still occur. Feedback and bug reports are welcome!

TrayApp gives your desktop app a system‑tray/menu‑bar icon and a tiny popup window for quick actions. It's perfect for quick toggles, mini dashboards, and "control center" UIs.

Works on Windows, macOS, and Linux. Smooth fade animations, smart positioning near the tray, and a simple API so you stay productive.

📦 Dependency: TrayApp lives in a separate artifact so basic-tray users don't pull in the windowing backend. Add it in addition to the core:
implementation("dev.nucleusframework:composenativetray-app:<version>")
It requires the Nucleus Tao backend — launch your app with nucleusApplication { … }. TrayApp, TrayAppState, rememberTrayAppState and TrayWindowDismissMode live in the dev.nucleusframework.composenativetray.trayapp package. See the TrayAppDemo in the demo module for a complete example.

Why you’ll like it

One‑click popup anchored to the tray/menu bar
Auto‑dismiss on outside click (or manual if you prefer)
State preserved: toggling visibility doesn’t remount your UI
Easy sizing with setWindowSize(...)
Tray menu builder for quick actions
Theming: transparent/undecorated styles for a modern look

Quick Start (minimal)

nucleusApplication {
    val trayAppState = rememberTrayAppState(
        initialWindowSize = DpSize(300.dp, 420.dp),
        initiallyVisible = true // default is false
        // initialDismissMode defaults to TrayWindowDismissMode.AUTO
    )

    TrayApp(
        state = trayAppState,
        icon = Icons.Default.Dashboard,   // required (or Painter / platform-specific overloads)
        tooltip = "My Tray App",          // required

        // Optional visual controls (defaults shown below)
        undecorated = true,               // default = true
        resizable = false,                // default = false
        windowsTitle = "My Tray Popup",   // default = "" — recommended (esp. on Linux & when undecorated=false)
        windowIcon = null,                // default = null — set your app icon; important on Linux & when undecorated=false

        menu = {                          // optional (default = null)
            Item("Toggle popup") { trayAppState.toggle() }
            Divider()
            Item("Quit") { exitApplication() }
        }
    ) {
        // Your Compose UI (DialogWindowScope receiver)
        MaterialTheme {
            Text("Quick Settings")
            Button(onClick = { trayAppState.hide() }) { Text("Close") }
        }
    }
}

Common recipes

Show / Hide / Toggle

trayAppState.show()
trayAppState.hide()
trayAppState.toggle()

Resize the popup

trayAppState.setWindowSize(400.dp, 600.dp)
// or
trayAppState.setWindowSize(DpSize(250.dp, 350.dp))

Dismiss mode

// AUTO (default): closes when user clicks outside or focus is lost
val state = rememberTrayAppState(initialDismissMode = TrayWindowDismissMode.AUTO)

// MANUAL: you decide when to hide
LaunchedEffect(Unit) {
    state.setDismissMode(TrayWindowDismissMode.MANUAL)
}

Tray menu (compact)

TrayApp(
    state = trayAppState,
    icon = Icons.Default.Settings,
    tooltip = "Quick Settings",
    menu = {
        val isVisible by trayAppState.isVisible.collectAsState()
        Item(if (isVisible) "Hide" else "Show") { trayAppState.toggle() }
        SubMenu("Size") {
            Item("250×350") { trayAppState.setWindowSize(250.dp, 350.dp) }
            Item("350×500") { trayAppState.setWindowSize(350.dp, 500.dp) }
            Item("450×600") { trayAppState.setWindowSize(450.dp, 600.dp) }
        }
    }
) {
    // your content
}

Tips

Title & icon matter: set windowsTitle and windowIcon. Even with undecorated UIs, Linux desktop environments often show a dock/taskbar entry; providing a title/icon prevents generic placeholders and improves discoverability.

📱 Apps Using Compose Native Tray

App	Description
AB Download Manager	A desktop download manager
RIFT Intel Fusion Tool	A tool for EVE Online

If your app uses Compose Native Tray, feel free to open a PR to add it here!

📄 License

This library is licensed under the MIT License. The Linux module uses Apache 2.0

🤝 Contribution

Contributions are welcome! Feel free to:

Report bugs via issues
Propose new features
Submit pull requests
Share your projects using this library

👨‍💻 Author

Developed and maintained by Elie Gambache with the goal of providing a modern, cross-platform solution for system tray icons in Kotlin.

Name		Name	Last commit message	Last commit date
Latest commit History 703 Commits
.github		.github
.idea		.idea
.run		.run
config/detekt		config/detekt
demo		demo
docs		docs
gradle		gradle
screenshots		screenshots
src		src
tray-app		tray-app
.editorconfig		.editorconfig
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
build.gradle.kts		build.gradle.kts
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle.kts		settings.gradle.kts

Uh oh!

Folders and files

Latest commit

History

Repository files navigation