Electron Window Corner Addon

A native macOS window corner radius addon for Electron applications that provides rounded corners and vibrancy effects.

Features

• ✨ Native Window Corners - Add native macOS-style rounded corners to Electron windows
• 🌈 Vibrancy Effects - Support for multiple macOS vibrancy materials
• 🎨 Dark Mode Support - Automatic adaptation to system theme changes
• ⚡ High Performance - Implemented with native Swift and C++
• 🔧 TypeScript Support - Complete type definitions included
• 🪟 Real-time Configuration - Dynamic corner radius and effect adjustment

Requirements

• OS: macOS 10.15+ (Catalina and above)
• Node.js: 16.0.0+
• Electron: 35.0.0+
• Architecture: x64, arm64 (supports Intel and Apple Silicon)

Installation

npm

npm install electron-window-corner-addon

pnpm

pnpm add electron-window-corner-addon

yarn

yarn add electron-window-corner-addon

Basic Usage

Import the Module

import { WindowCorner, VibrancyMaterial, EffectState } from 'electron-window-corner-addon'
import { BrowserWindow } from 'electron'

Create a Window with Rounded Corners

// Create a transparent window
const window = new BrowserWindow({
  width: 800,
  height: 600,
  frame: false,
  transparent: true,
  titleBarStyle: 'hiddenInset',
  webPreferences: {
    // your webPreferences
  }
})

// Apply corner radius and vibrancy effect
WindowCorner.setCornerRadius(
  window,
  24, // Corner radius in pixels
  VibrancyMaterial.UNDER_WINDOW_BACKGROUND, // Vibrancy material
  EffectState.ACTIVE // Effect state
)

API Reference

WindowCorner.setCornerRadius()

Set corner radius and vibrancy effect for a window.

WindowCorner.setCornerRadius(
  view: BrowserWindow,
  radius?: number,
  vibrancyMaterial?: VibrancyMaterialType,
  effectState?: EffectStateType
): boolean

Parameters:

• view - Electron BrowserWindow instance
• radius - Corner radius in pixels (default: 32)
• vibrancyMaterial - Vibrancy material (default: 'under-window-background')
• effectState - Effect state (default: 'active')

Returns: true if successful, false if failed

WindowCorner.getCornerRadius()

Get the current corner radius of a window.

WindowCorner.getCornerRadius(view: BrowserWindow): number

Returns: Current corner radius, or -1 if not set or error occurred

Other Methods

// Check if the module is available (macOS only)
WindowCorner.isAvailable(): boolean

// Set debug mode
WindowCorner.setDebugMode(enabled: boolean): void

// Get debug mode status
WindowCorner.getDebugMode(): boolean

Vibrancy Materials

enum VibrancyMaterial {
  TITLEBAR = 'titlebar',                           // Title bar
  SELECTION = 'selection',                         // Selection
  MENU = 'menu',                                   // Menu
  POPOVER = 'popover',                            // Popover
  SIDEBAR = 'sidebar',                            // Sidebar
  HEADER_VIEW = 'header-view',                    // Header view
  SHEET = 'sheet',                                // Sheet
  WINDOW_BACKGROUND = 'window-background',         // Window background
  HUD_WINDOW = 'hudWindow',                       // HUD window
  FULL_SCREEN_UI = 'full-screen-ui',              // Full screen UI
  TOOL_TIP = 'tool-tip',                          // Tool tip
  CONTENT_BACKGROUND = 'content-background',       // Content background
  UNDER_WINDOW_BACKGROUND = 'under-window-background' // Under window background (recommended)
}

Effect States

enum EffectState {
  ACTIVE = 'active',                              // Active state
  INACTIVE = 'inactive',                          // Inactive state
  FOLLOWS_WINDOW_ACTIVE_STATE = 'followsWindowActiveState' // Follows window active state
}

Complete Example

import { app, BrowserWindow } from 'electron'
import { WindowCorner, VibrancyMaterial, EffectState } from 'electron-window-corner-addon'

async function createWindow() {
  // Create window
  const mainWindow = new BrowserWindow({
    width: 1200,
    height: 800,
    frame: false,
    transparent: true,
    titleBarStyle: 'hiddenInset',
    webPreferences: {
      nodeIntegration: false,
      contextIsolation: true
    }
  })

  // Check module availability
  if (WindowCorner.isAvailable()) {
    console.log('WindowCorner module is available')
    
    // Enable debug mode (optional)
    WindowCorner.setDebugMode(true)
    
    // Apply corner radius effect
    const success = WindowCorner.setCornerRadius(
      mainWindow,
      28, // 28px corner radius
      VibrancyMaterial.UNDER_WINDOW_BACKGROUND,
      EffectState.ACTIVE
    )
    
    if (success) {
      console.log('Corner radius effect applied successfully')
      
      // Get current corner radius
      const currentRadius = WindowCorner.getCornerRadius(mainWindow)
      console.log(`Current corner radius: ${currentRadius}px`)
    } else {
      console.log('Failed to apply corner radius effect')
    }
  } else {
    console.log('WindowCorner module not available (may not be macOS)')
  }

  // Load application
  await mainWindow.loadFile('index.html')
  
  // Show window
  mainWindow.show()
}

app.whenReady().then(createWindow)

Recommended CSS

For the best visual effect, use the following styles in your HTML/CSS:

body {
  margin: 0;
  padding: 0;
  background: transparent;
  /* Avoid white background flashing */
  -webkit-app-region: drag; /* Make entire window draggable */
}

/* Ensure content areas are not draggable */
.content {
  -webkit-app-region: no-drag;
}

/* Optimize for dark mode */
@media (prefers-color-scheme: dark) {
  body {
    color: #ffffff;
  }
}

Testing & Debugging

This project includes an interactive testing tool:

# Run test interface
npm test

This will open a test window where you can adjust corner radius, vibrancy materials, and effect states in real-time.

Build Notes

Development Build

# Install dependencies
npm install

# Build TypeScript
npm run build:ts

# Build native module (macOS only)
npm run build:native

# Complete build
npm run build

Clean Build Files

npm run clean

Known Limitations

1. macOS Only - This addon only works on macOS systems
2. Requires Transparent Window - Window must be set to transparent: true
3. Requires Frameless Window - Recommended to use frame: false or titleBarStyle: 'hiddenInset'

Troubleshooting

Corner Effect Not Showing

1. Ensure window is set to transparent: true
2. Check if running on macOS system
3. Ensure native module is compiled correctly

Build Failures

1. Ensure Xcode Command Line Tools are installed
2. Check Node.js version is >= 16.0.0
3. Try reinstalling dependencies: rm -rf node_modules && npm install

Debug Information

// Enable debug mode to see detailed logs
WindowCorner.setDebugMode(true)

// Check module status
console.log('Module available:', WindowCorner.isAvailable())
console.log('Debug mode:', WindowCorner.getDebugMode())

Acknowledgments

Special thanks to @STRRL for his valuable insights and contributions to the native macOS window corner radius solution. His work and expertise in macOS development have been instrumental in making this project possible.

Be sure to check out his amazing AI chat assistant for macOS: Haye AI - A private macOS AI assistant that lets you experience top-tier models like DeepSeek R1, GPT-4.1, o3, Claude-3.7, and Gemini-2.5 in a single app.

License

2025 © Innei, Released under the MIT License.

Personal Website · GitHub @Innei