{"id":30750353,"url":"https://github.com/Meridius-Labs/electron-liquid-glass","last_synced_at":"2025-09-04T07:03:38.189Z","repository":{"id":299521323,"uuid":"1003199599","full_name":"Meridius-Labs/electron-liquid-glass","owner":"Meridius-Labs","description":"Electron bindings for Apple Liquid Glass","archived":false,"fork":false,"pushed_at":"2025-08-10T20:04:51.000Z","size":110,"stargazers_count":143,"open_issues_count":8,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-10T22:10:48.553Z","etag":null,"topics":["electron","glass","javascript","liquid","liquid-ass","liquid-glass"],"latest_commit_sha":null,"homepage":"","language":"Objective-C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Meridius-Labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"avarayr","buy_me_a_coffee":"avarayr"}},"created_at":"2025-06-16T19:25:03.000Z","updated_at":"2025-08-10T20:04:55.000Z","dependencies_parsed_at":"2025-06-17T01:27:12.605Z","dependency_job_id":"30200db4-2c3a-453d-ac85-afaa983d3d97","html_url":"https://github.com/Meridius-Labs/electron-liquid-glass","commit_stats":null,"previous_names":["meridius-labs/electron-liquid-glass"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/Meridius-Labs/electron-liquid-glass","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Meridius-Labs%2Felectron-liquid-glass","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Meridius-Labs%2Felectron-liquid-glass/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Meridius-Labs%2Felectron-liquid-glass/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Meridius-Labs%2Felectron-liquid-glass/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Meridius-Labs","download_url":"https://codeload.github.com/Meridius-Labs/electron-liquid-glass/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Meridius-Labs%2Felectron-liquid-glass/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273567781,"owners_count":25128640,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-04T02:00:08.968Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["electron","glass","javascript","liquid","liquid-ass","liquid-glass"],"created_at":"2025-09-04T07:01:17.849Z","updated_at":"2025-09-04T07:03:37.888Z","avatar_url":"https://github.com/Meridius-Labs.png","language":"Objective-C++","funding_links":["https://github.com/sponsors/avarayr","https://buymeacoffee.com/avarayr"],"categories":["Objective-C++"],"sub_categories":[],"readme":"# electron-liquid-glass\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg width=\"387\" alt=\"image\" src=\"https://github.com/user-attachments/assets/3c3c9ea6-2663-4292-b812-a630c2c3f65b\" /\u003e\n\n![npm](https://img.shields.io/npm/v/electron-liquid-glass)\n![npm downloads](https://img.shields.io/npm/dm/electron-liquid-glass)\n![GitHub](https://img.shields.io/github/license/meridius-labs/electron-liquid-glass)\n![Platform](https://img.shields.io/badge/platform-macOS-blue)\n![Node](https://img.shields.io/node/v/electron-liquid-glass)\n\n**Modern macOS glass effects for Electron applications**\n\n_🪄 NATIVE `NSGlassEffectView` integration with ZERO CSS hacks_\n\n[Installation](#-installation) • [Quick Start](#-quick-start) • [API](#-api-reference) • [Examples](examples/) • [Contributing](#-contributing)\n\n\u003c/div\u003e\n\n---\n\n## ✨ Features\n\n- 🪟 **Native Glass Effects** - Real `NSGlassEffectView` integration, not CSS approximations\n- ⚡ **Zero Configuration** - Works out of the box with any Electron app\n- 🎨 **Fully Customizable** - Corner radius, tint colors, and glass variants\n- 📦 **Modern Package** - Dual ESM/CommonJS support with TypeScript declarations\n- 🔧 **Pre-built Binaries** - No compilation required for standard setups\n- 🌙 **Auto Dark Mode** - Automatically adapts to system appearance changes\n\n## 🚀 Installation\n\n```bash\n# npm\nnpm install electron-liquid-glass\n\n# yarn\nyarn add electron-liquid-glass\n\n# pnpm\npnpm add electron-liquid-glass\n\n# bun\nbun add electron-liquid-glass\n```\n\n### Requirements\n\n- **macOS 26+** (Tahoe or later)\n- **Electron 30+**\n- **Node.js 22+**\n\n\u003e **Note**: This package only works on macOS. On other platforms, it provides safe no-op fallbacks.\n\n## 🎯 Quick Start\n\n### Basic Usage\n\n```javascript\nimport { app, BrowserWindow } from \"electron\";\nimport liquidGlass from \"electron-liquid-glass\";\n\napp.whenReady().then(() =\u003e {\n  const win = new BrowserWindow({\n    width: 800,\n    height: 600,\n\n    vibrancy: false, // \u003c-- ❌❌❌ do NOT set vibrancy alongside with liquid glass, it will override and look blurry\n\n    transparent: true, // \u003c-- This MUST be true\n  });\n\n  win.setWindowButtonVisibility(true); // \u003c-- ✅ This is required to show the window buttons\n\n  win.loadFile(\"index.html\");\n\n  /**\n   * 🪄 Apply glass effect after content loads 🪄\n   */\n  win.webContents.once(\"did-finish-load\", () =\u003e {\n    // 🪄 Apply effect, get handle\n    const glassId = liquidGlass.addView(win.getNativeWindowHandle(), {\n      /* options */\n    });\n\n    // Experimental, undocumented private APIs\n    liquidGlass.unstable_setVariant(glassId, 2);\n  });\n});\n```\n\n### TypeScript Usage\n\n```typescript\nimport { BrowserWindow } from \"electron\";\nimport liquidGlass, { GlassOptions } from \"electron-liquid-glass\";\n\nconst options: GlassOptions = {\n  cornerRadius: 16, // (optional)\n  tintColor: \"#44000010\", // black tint (optional)\n  opaque: true, // add opaque background behind glass (optional)\n};\n\nliquidGlass.addView(window.getNativeWindowHandle(), options);\n```\n\n## 📚 API Reference\n\n### `liquidGlass.addView(handle, options?)`\n\nApplies a glass effect to an Electron window.\n\n**Parameters:**\n\n- `handle: Buffer` - The native window handle from `BrowserWindow.getNativeWindowHandle()`\n- `options?: GlassOptions` - Configuration options\n\n**Returns:** `number` - A unique view ID for future operations\n\n### `GlassOptions`\n\n```typescript\ninterface GlassOptions {\n  cornerRadius?: number; // Corner radius in pixels (default: 0)\n  tintColor?: string; // Hex color with optional alpha (#RRGGBB or #RRGGBBAA)\n  opaque?: boolean; // Add opaque background behind glass (default: false)\n}\n```\n\n---\n\n### UNDOCUMENTED EXPERIMENTAL METHODS\n\n\u003e ⚠️ **Warning**: DO NOT USE IN PROD. These methods use private macOS APIs and may change in future versions.\n\n```typescript\n// Glass variants (number) (0-15, 19 are functional)\nliquidGlass.unstable_setVariant(glassId, 2);\n\n// Scrim overlay (0 = off, 1 = on)\nliquidGlass.unstable_setScrim(glassId, 1);\n\n// Subdued state (0 = normal, 1 = subdued)\nliquidGlass.unstable_setSubdued(glassId, 1);\n```\n\n## 🔧 Development\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/meridius-labs/electron-liquid-glass.git\ncd electron-liquid-glass\n\n# Install dependencies\nbun install\n\n# Build native module\nbun run build:native\n\n# Build TypeScript library\nbun run build\n\n# Build everything\nbun run build:all\n```\n\n### Rebuilding for Custom Electron\n\nIf you're using a custom Electron version:\n\n```bash\nnpx electron-rebuild -f -w electron-liquid-glass\n```\n\n### Project Structure\n\n```\nelectron-liquid-glass/\n├── src/                 # Native C++ source code\n│   ├── glass_effect.mm  # Objective-C++ implementation\n│   └── liquidglass.cc   # Node.js addon bindings\n├── js/                  # TypeScript source\n│   ├── index.ts         # Main library code\n│   └── native-loader.ts # Native module loader\n├── dist/                # Built library (generated)\n├── examples/            # Example applications\n└── prebuilds/          # Pre-built binaries\n```\n\n## 🏗️ How It Works\n\n1. **Native Integration**: Uses Objective-C++ to create `NSGlassEffectView` instances\n2. **View Hierarchy**: Inserts glass views behind your web content, not over it\n3. **Automatic Updates**: Listens for system appearance changes to keep effects in sync\n4. **Memory Management**: Properly manages native view lifecycle\n\n### Technical Details\n\n- **Primary**: Uses `NSGlassEffectView` API when available\n- **Fallback**: Falls back to public `NSVisualEffectView` on older systems\n- **Performance**: Minimal overhead, native rendering performance\n- **Compatibility**: Works with all Electron window configurations\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes and test thoroughly\n4. Commit with conventional commits: `git commit -m \"feat: add amazing feature\"`\n5. Push and create a Pull Request\n\n### Reporting Issues\n\n- Use the [issue tracker](https://github.com/meridius-labs/electron-liquid-glass/issues)\n- Include your macOS version, Electron version, and Node.js version\n- Provide a minimal reproduction case when possible\n\n## 📋 Roadmap\n\n- [ ] **View Management** - Remove and update existing glass views\n\n## 🙏 Acknowledgments\n\n- Apple's private `NSGlassEffectView` API documentation (reverse-engineered)\n- The Electron team for excellent native integration capabilities\n- Contributors and users who help improve this library\n\n## 📄 License\n\nMIT © [Meridius Labs](https://github.com/meridius-labs) 2025\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ for the Electron community**\n\n[⭐ Star on GitHub](https://github.com/meridius-labs/electron-liquid-glass) • [🐛 Report Bug](https://github.com/meridius-labs/electron-liquid-glass/issues) • [💡 Request Feature](https://github.com/meridius-labs/electron-liquid-glass/issues)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMeridius-Labs%2Felectron-liquid-glass","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMeridius-Labs%2Felectron-liquid-glass","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMeridius-Labs%2Felectron-liquid-glass/lists"}