# Cherry Studio Transparent Windows: How Electron Transparency Works on macOS

> Learn how Cherry Studio achieves transparent windows on macOS using Electron transparency and vibrancy effects. Explore platform-specific settings for mini windows.

- Repository: [CherryHQ/cherry-studio](https://github.com/cherryhq/cherry-studio)
- Tags: internals
- Published: 2026-02-27

---

**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`](https://github.com/cherryhq/cherry-studio/blob/main/src/main/services/WindowService.ts), the window instantiation checks the platform before setting the transparent flag:

```typescript
// 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`](https://github.com/cherryhq/cherry-studio/blob/main/src/main/services/SelectionService.ts), this window explicitly enables transparency to function as a floating interface element:

```typescript
// 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`](https://github.com/cherryhq/cherry-studio/blob/main/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:

```typescript
// 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`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/pages/settings/DisplaySettings/DisplaySettings.tsx) exposes a toggle switch that dispatches the `setWindowStyle` action:

```typescript
// 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`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/pages/home/components/SelectModelButton.tsx), the component sets:

```css
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:

```typescript
// 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`](https://github.com/cherryhq/cherry-studio/blob/main/WindowService.ts) while the toolbar window uses `transparent: true` in [`SelectionService.ts`](https://github.com/cherryhq/cherry-studio/blob/main/SelectionService.ts)
- **State Management**: The `windowStyle` setting in [`settings.ts`](https://github.com/cherryhq/cherry-studio/blob/main/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.