@electron-uikit/titlebar
v1.1.0
Published
Title bar web component for Electron app.
Downloads
8
Readme
@electron-uikit/titlebar
Title bar web component for Electron app.
The title bar web component is used to simulate the Windows title bar for better customization. It's very easy to use and get the same experience as a native title bar. Fully compatible with Windows, MacOS and Linux.
Features
- Customization
- Fully compatible with Windows, MacOS and Linux.
- Support dark mode
- Based on Web component
Usage
Install
npm i @electron-uikit/core @electron-uikit/titlebarGet Started
Exposes the UI Kit APIs for components. See @electron-uikit/core guide for more details.
You can expose it in the specified preload script:
import { exposeUIKit } from '@electron-uikit/core/preload' exposeUIKit()Or, you can expose it globally in the main process for all renderer processes:
import { useUIKit } from '@electron-uikit/core/main' useUIKit()
[!NOTE] If you are using @electron-toolkit/preload to expose Electron APIs, there is no need to use this module, because
coreis also an export of it.
Register a listener and attach a title bar to the window in the main process, so that you can use it in the renderer process.
import { app, BrowserWindow } from 'electron' import { registerTitleBarListener, attachTitleBarToWindow } from '@electron-uikit/titlebar' app.whenReady().then(() => { // Register title bar IPC listeners registerTitleBarListener() // Create a window without title bar const win = new BrowserWindow({ titleBarStyle: 'hidden' }) // Attach a title bar to the window attachTitleBarToWindow(win) })Use the title bar web component in window html page.
<head> <!-- Import the title bar web component module in html header or its entry file --> <script type="module"> import '@electron-uikit/titlebar/renderer' </script> </head> <body> <!-- You can customize the title bar height using a class or style --> <title-bar windowtitle="Electron UIKit" style="height: 32px;"></title-bar> </body>
Components
Attributes
| Attribute | Description | Type | Default |
| ------------------- | -------------------------------------------------------------------- | --------- | ------- |
| windowtitle | Window title | string | - |
| overlay | Set window controls overlay | boolean | false |
| nominimize | If specified, the title bar will not show the minimization control | boolean | false |
| nomaximize | If specified, the title bar will not show the nomaximization control | boolean | false |
| noclose | If specified, the title bar will not show the x control | boolean | false |
| supportfullscreen | Support fullscreen window mode | boolean | false |
CSS Properties
| Property | Description | Default |
| --------------------------- | ----------------------------- | ----------------------------------------------------- |
| --tb-theme-color | Theme color | light: #ffffff, dark: #1f1f1f |
| --tb-title-text-color | Window title text color | light: #333333, dark: #cccccc |
| --tb-title-font-family | Window title text font family | -apple-system, BlinkMacSystemFont, Ubuntu, 'Segoe UI' |
| --tb-control-symbol-color | Window control symbol color | light: #585c65, dark: #cccccc |
| --tb-control-hover-color | Window control hover color | light: #e1e1e1, dark: #373737 |
| --tb-control-height | Window control height | 26px (minimum height) |
| --tb-control-width | Window control width | 34px (minimum width) |
| --tb-control-margin | Window control margins | 3px (MacOS only) |
| --tb-control-radius | Window control radius | 5px (MacOS only) |
Customization
Theme Color
The default theme CSS is customizable by overriding the components CSS variables:
.titlebar {
height: 32px;
--tb-theme-color: #ffffff;
--tb-title-text-color: #333333;
--tb-control-symbol-color: #585c65;
--tb-control-hover-color: #e1e1e1;
}Support dark mode by overriding the component CSS variable with prefers-color-scheme:
@media (prefers-color-scheme: dark) {
.titlebar {
--tb-theme-color: #1f1f1f;
--tb-title-text-color: #cccccc;
--tb-control-symbol-color: #cccccc;
--tb-control-hover-color: #373737;
}
}Window Controls
Overlay modeThe titlebar only has window control display and no drag region for application.
<title-bar overlay class="titlebar"></title-bar>Control size and display<title-bar nomaximize style="--tb-control-height: 34px;"></title-bar>CustomizationIt is very easy to customize a window control, just define the control icon CSS and bind event handlers to the control element.
/* CSS style: control icon */ .icon { height: 13px; width: 13px; background-color: #333; mask-position: 50% 50%; mask-repeat: no-repeat; mask-size: 100%; } .icon-sun { mask-image: url(/sun.svg); } .icon-moon { mask-image: url(/moon.svg); }<title-bar id="titlebar" windowtitle="Electron UIKit" class="titlebar"> <!-- You can customize your window controls with "window__control" class --> <div id="control" class="window__control"> <i id="icon" class="icon icon-sun"></i> </div> </title-bar>const control = document.getElementById('control') control?.addEventListener('click', () => { // ... })
[!NOTE] Only elements with the
window__controlclass in the title bar slot will be recognized as window controls. Other elements will not be displayed.
Integrations
VS Code IDE
Add a file .vscode/settings.json with the following configuration:
{
"html.customData": [
"./node_modules/@electron-uikit/titlebar/custom-elements.json"
]
}VS Code will load additional title bar HTML entities, so they would show up in auto-completion, hover information etc.
TypeScript and TSX
If you are a TypeScript user, make sure to add a *.d.ts declaration file to get type checks and intellisense:
/// <reference types="@electron-uikit/titlebar/renderer" />For .tsx support, a React example:
import { HTMLTitleBarElementAttributes } from '@electron-uikit/titlebar/renderer'
declare global {
namespace JSX {
interface IntrinsicElements {
// Define an interface for the web component props
'title-bar': Partial<HTMLTitleBarElementAttributes>
}
}
}