Cherry Studio Transparent Windows: How Electron Transparency Works on macOS

Cherry Studio supports transparent windows on macOS through Electron's transparent BrowserWindow option combined with vibrancy effects, while the quick-access mini window and selection toolbar use platform-specific transparency settings.

Cherry Studio leverages Electron's window management capabilities to deliver native macOS aesthetics through transparent window styles. The application implements this feature across multiple window types—including the main interface, mini quick-assistant, and selection toolbar—using a combination of BrowserWindow configuration, Redux state management, and CSS styling.

How Cherry Studio Implements Window Transparency

The transparency system relies on Electron's BrowserWindow constructor options defined in the main process. Different window types utilize varying transparency strategies based on their functional requirements and platform constraints.

Mini Window Transparency Configuration

The mini window—responsible for Cherry Studio's quick-assistant feature—conditionally enables transparency only on macOS. In src/main/services/WindowService.ts, the window instantiation checks the platform before setting the transparent flag:

// src/main/services/WindowService.ts (lines 521-523)
this.miniWindow = new BrowserWindow({
  // ... other options
  transparent: isMac,            // true only on macOS
  vibrancy: 'under-window',
  frame: false,
  // ...
})

This conditional approach ensures that macOS users receive the native vibrancy effect while maintaining compatibility with Windows and Linux platforms where full transparency may cause rendering issues.

Toolbar Window Full Transparency

The selection toolbar operates as a frameless overlay window requiring complete transparency regardless of platform. Located in src/main/services/SelectionService.ts, this window explicitly enables transparency to function as a floating interface element:

// src/main/services/SelectionService.ts (lines 402-408)
this.toolbarWindow = new BrowserWindow({
  width: toolbarWidth,
  height: toolbarHeight,
  show: false,
  frame: false,
  transparent: true,            // forces full transparency
  alwaysOnTop: true,
  // ...
})

This configuration allows the toolbar to appear as a seamless overlay above other applications without window decorations or background color interference.

User-Controlled Transparency Settings

Cherry Studio provides granular user control over window transparency through a dedicated Redux state slice and corresponding UI components.

The windowStyle Configuration

The application stores the transparency preference in src/renderer/src/store/settings.ts using a windowStyle field that accepts either 'transparent' or 'opaque' values. The default setting automatically detects the operating system:

// src/renderer/src/store/settings.ts (line 281)
windowStyle: isMac ? 'transparent' : 'opaque',

This initialization ensures macOS users receive the transparent aesthetic by default while Windows and Linux users get opaque windows to avoid rendering artifacts.

Toggling Transparency in the UI

The Display Settings page located at src/renderer/src/pages/settings/DisplaySettings/DisplaySettings.tsx exposes a toggle switch that dispatches the setWindowStyle action:

// src/renderer/src/pages/settings/DisplaySettings/DisplaySettings.tsx (lines 283-286)
const handleChange = (checked: boolean) => {
  setWindowStyle(checked ? 'transparent' : 'opaque');
};

<Switch checked={windowStyle === 'transparent'} onChange={handleChange} />

When users toggle this setting, the application updates the Redux store and triggers CSS recalculations throughout the renderer process.

macOS-Specific Visual Effects

Transparency on macOS extends beyond the Electron window flag to include native vibrancy effects and careful CSS coordination.

Vibrancy and Visual Effect States

The main application window and mini window both leverage macOS-specific vibrancy options to create the frosted-glass appearance. The main window uses vibrancy: 'sidebar' while the mini window uses vibrancy: 'under-window'. Additionally, the visualEffectState: 'active' property ensures the vibrancy effect remains active regardless of window focus state.

These properties interact with the transparent: true setting to allow the desktop wallpaper or underlying content to show through with the characteristic macOS blur effect.

CSS Transparency Handling

When the transparent window style is active, UI components throughout the renderer process adjust their backgrounds accordingly. For example, in src/renderer/src/pages/home/components/SelectModelButton.tsx, the component sets:

background-color: transparent;

The application uses a custom hook, useNavBackgroundColor, to dynamically determine whether to apply transparent or themed backgrounds based on the windowStyle state:

// src/renderer/src/hooks/useNavBackgroundColor.ts
const { windowStyle } = useSettings();
const macTransparent = isMac && windowStyle === 'transparent';
const background = macTransparent ? 'transparent' : theme.background;

This coordinated approach ensures that HTML backgrounds do not obstruct the native vibrancy effects while maintaining readability across different themes.

Summary

Cherry Studio achieves window transparency through a multi-layered approach combining Electron APIs and platform-specific optimizations:

• BrowserWindow Configuration: The mini window uses transparent: isMac in WindowService.ts while the toolbar window uses transparent: true in SelectionService.ts
• State Management: The windowStyle setting in settings.ts defaults to transparent on macOS and opaque on other platforms
• User Interface: Display settings provide a toggle switch to change between transparent and opaque modes
• macOS Integration: Vibrancy effects (under-window, sidebar) combined with CSS background-color: transparent create native frosted-glass aesthetics

Frequently Asked Questions

Does Cherry Studio support transparent windows on Windows and Linux?

No, transparent windows are primarily supported on macOS. The codebase explicitly checks isMac before enabling the transparent flag for the mini window, and the default windowStyle setting uses 'opaque' on non-macOS platforms. While the selection toolbar uses transparent: true universally, this serves a specific overlay function rather than aesthetic transparency.

How do I enable transparent window mode in Cherry Studio?

Navigate to Settings > Display and toggle the "Transparent window" switch. This updates the windowStyle Redux state from 'opaque' to 'transparent'. On macOS, this change takes effect immediately, allowing the vibrancy effects to show through the UI. The setting persists across application restarts through the Redux store persistence mechanism.

What is the difference between the mini window and toolbar transparency?

The mini window (quick assistant) uses conditional transparency (transparent: isMac) to provide a native macOS aesthetic with vibrancy effects, while remaining opaque on other platforms for compatibility. The selection toolbar uses unconditional transparency (transparent: true) to function as a floating, frameless overlay window that appears above other applications regardless of platform, serving a functional rather than aesthetic purpose.

Does transparency affect performance?

Transparency and vibrancy effects may have minor performance implications on macOS due to the additional compositing required for the frosted-glass visual effects. However, Cherry Studio mitigates this by only enabling full transparency on macOS where the GPU efficiently handles these effects, and by using CSS background-color: transparent to avoid unnecessary paint operations. Users experiencing performance issues can switch to "Opaque" mode in Display Settings to disable these effects.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}