https://github.com/cristian006/frameless-titlebar
Customizable Electron Titlebar for frameless windows
https://github.com/cristian006/frameless-titlebar
custom custom-titlebar customizable desktop desktop-app desktop-application electron electron-titlebar frameless frameless-windows macos menubar react submenu themable titlebar toolbar typescript windows
Last synced: about 1 month ago
JSON representation
Customizable Electron Titlebar for frameless windows
- Host: GitHub
- URL: https://github.com/cristian006/frameless-titlebar
- Owner: Cristian006
- License: mit
- Created: 2018-05-18T01:59:18.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T01:59:16.000Z (over 2 years ago)
- Last Synced: 2025-03-27T11:24:43.058Z (about 2 months ago)
- Topics: custom, custom-titlebar, customizable, desktop, desktop-app, desktop-application, electron, electron-titlebar, frameless, frameless-windows, macos, menubar, react, submenu, themable, titlebar, toolbar, typescript, windows
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/frameless-titlebar
- Size: 8.58 MB
- Stars: 216
- Watchers: 7
- Forks: 35
- Open Issues: 51
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# frameless-titlebar
[](https://www.npmjs.com/package/frameless-titlebar)  
> Customizable titlebar for frameless electron windows built with React
![Main][main]
## [Demo App](https://cristian006.github.io/frameless-titlebar)
The demo application can be found in the [example](./example) folder along with more images of the different titlebar styles:
* [Overflow Menu](./example/public/overflow.jpg): When menu buttons don't fit in the given titlebar space items are moved into an overflowed submenu.
* [Stacked Menu](./example/public/stacked.png): Titlebar stacked above menu bar.
* [Vertical Menu](./example/public/vertical.png): All menu items moved into a vertical submenu.
## Install
```bash
npm install --save frameless-titlebar
# or
yarn add frameless-titlebar
```
## Usage
Electron Browser SetUp
```js
mainWindow = new BrowserWindow({
width: 1024,
height: 728,
minWidth: 600, // set a min width!
minHeight: 300, // and a min height!
// Remove the window frame from windows applications
frame: false,
// Hide the titlebar from MacOS applications while keeping the stop lights
titleBarStyle: 'hidden',
});
```
React App SetUp
```jsx
import React from 'react'
import icon from 'path/to/icon.png';
import menu from 'path/to/menu';
import { remote } from 'electron';
import TitleBar from 'frameless-titlebar'
const currentWindow = remote.getCurrentWindow();
const Example = () => {
// manage window state, default to currentWindow maximized state
const [maximized, setMaximized] = useState(currentWindow.isMaximized());
// add window listeners for currentWindow
useEffect(() => {
const onMaximized = () => setMaximized(true);
const onRestore = () => setMaximized(false);
currentWindow.on("maximize", onMaximized);
currentWindow.on("unmaximize", onRestore);
return () => {
currentWindow.removeListener("maximize", onMaximized);
currentWindow.removeListener("unmaximize", onRestore);
}
}, []);
// used by double click on the titlebar
// and by the maximize control button
const handleMaximize = () => {
if (maximized) {
currentWindow.restore();
} else {
currentWindow.maximize();
}
}
return (
currentWindow.close()}
onMinimize={() => currentWindow.minimize()}
onMaximize={handleMaximize}
// when the titlebar is double clicked
onDoubleClick={handleMaximize}
// hide minimize windows control
disableMinimize={false}
// hide maximize windows control
disableMaximize={false}
// is the current window maximized?
maximized={maximized}
>
{/* custom titlebar items */}
)
}
```
> Example of all of the overridable theme properties can be found in the example folder [here](./example/README.md)
Use titlebar theme in children
```jsx
import { useContext } from 'react';
import { TitlebarThemeContext } from 'frameless-titlebar';
const CustomItem = () => {
// access all of the current theme properties in this
// child component
const theme = useContext(TitlebarThemeContext);
return (
{/* ... */}
)
}
const App = () => {
return (
)
}
```
> Example of a custom TitleBarButton can be seen [here](./example/src/components.js)
## Supported Menu Item Properties
Supported menu item properties from:
[Electron Menu Object/Template Documentation](https://electronjs.org/docs/api/menu "Electron Menu Documentation")
| Name | Type | Description |
| :--- | :--: | :---------- |
| `id` (optional) | `string` | Must be unique. If defined then it can be used as a reference to this item by the position attribute |
| `type` (optional) | oneOf([`normal`, `separator`, `submenu`, `checkbox`, `radio`]) | Type of supported menu items |
| `label` (optional) | `string` | Menu item label |
| `click` (optional) | `function(menuItem, browserWindow, event)` | if `currentWindow` is not passed in to the titlebar then, `browserWindow` will be null |
| `disabled` (optional) | `bool` | Enables/disables menu item from being clicked on |
| `accelerator` (optional) | `string` | Accelerator string eg `CmdOrCtrl+Z`|
| `icon` (optional) | `img` | The image shown to the left of the menu label |
| `checked` (optional) | `bool` | Should only be specified for checkbox or radio type menu items |
| `submenu` (optional) | `array : [MenuItems]` | Array of menu items. If `submenu` is specified, the `type: 'submenu'` can be omitted. |
| `before` (optional) | `string` | Inserts this item before the item with the specified id. If the referenced item doesn't exist the item will be inserted at the end of the menu |
| `after` (optional) | `string` | Inserts this item after the item with the specified id. If the referenced item doesn't exist the item will be inserted at the end of the menu |
## Keyboard accessibility
**Opening Menu**: Pressing `Alt` Key + First letter of any of the visible menu items. eg: `Alt+F` would open the first menu item with an `F` if any, such as `File`.
**Closing Menu**: Pressing `Esc`.
**Navigating Submenus**: Use arrow keys (up, down, left, right) to navigate menus once they're open.
## Disclaimers
**NOTE**: `^v2.0.0` has a lot of breaking changes from the previous `^1.x.x` releases since this was a complete re-write of frameless-titlebar
## Contributing
Feel free to fork and create pull requests! I'll try my best to review any code changes for the next release.
## Links
[Electron Remote Docs](https://www.electronjs.org/docs/api/remote#remotegetcurrentwindow)
[Electron Menu Docs](https://electronjs.org/docs/api/menu "Electron Menu Documentation")
## License
MIT © [Cristian006](https://github.com/Cristian006)
---
[main]: ./example/public/default.png "Main"