Features
-
💾 Persistent - persistently stores your Electron Window's size and position -
🔌 Easy integration - integrates easily with your existing BrowserWindow configuration -
🔨 Customization - customize the behaviour and the underlying electron-store instance -
🖼️ Frame option - you can optionally store the frame option as well
🚀 Get started
npm install electron-win-state
Requires Electron 11 or later
📚 Usage
The easiest way to use electron-win-state, is to add it as a wrapper around your normal BrowserWindow
:
import WinState from 'electron-win-state'
const browserWindow = WinState.createBrowserWindow({
width: 800,
height: 600,
// your normal BrowserWindow options...
})
This will create a new BrowserWindow
with the provided options and store any changes once the window is closed.
Thats it! Your Electron app now has a persistent window!
Manually
You can also use electron-win-state manually:
const winState = new WinState({
defaultWidth: 800,
defaultHeight: 600,
// other winState options, see below
})
const browserWindow = new BrowserWindow({
...winState.winOptions,
// your normal BrowserWindow options...
})
// Attach the required event listeners
winState.manage(this.browserWindow)
With winState.winOptions
you have access to the restored size and position of the window:
console.log(winState.winOptions) // => { width: 800, height: 600, x: 0, y: 0, frame: true }
⚙️ Options
You can customize the behaviour of electron-win-state further, by passing an options object to new WinState()
or by specifying a winState
object when using .createBrowserWindow()
:
new WinState({
defaultWidth: 800,
defaultHeight: 600,
dev: true,
addMethods: true
})
Or:
WinState.createBrowserWindow({
winState: {
defaultWidth: 800,
defaultHeight: 600,
dev: true,
addMethods: true
}
})
Or:
WinState.createBrowserWindow({
width: 800,
height: 600,
winState: {
dev: true,
addMethods: true
}
})
All of these result in the same.
Here are all the options electron-win-state supports:
Name | Type | Description | Default |
---|---|---|---|
defaultWidth |
number |
The default width which will be used when no stored value was found | 800 |
defaultHeight |
number |
The default height which will be used when no stored value was found | 600 |
defaultFrame |
boolean |
The default value for the frame option when no stored value was found | true |
storeFrameOption |
boolean |
Store and restore the frame option (will be enabled automatically if defaultFrame is provided) |
false |
dev |
boolean |
Enable development mode. Changes will be stored immediately after resizing or moving and not just after closing a window | false |
addMethods |
boolean |
Add the .resetWindowToDefault() , .setFramed() and .getStoredWinOptions() methods to the provided BrowserWindow
|
true |
electronStoreOptions |
object |
Will be passed to the underlying electron-store instance | { name: 'window-state' } |
store |
instance |
An existing electron-store instance to use | n/a |
📖 Examples
Here are a few examples to help you get started!
Basic Example
This is the most basic example. A new BrowserWindow will be created and the required event listeners will be attached automatically.
import WinState from 'electron-win-state'
const browserWindow = WinState.createBrowserWindow({
width: 800,
height: 600
})
browserWindow.loadURL('https://github.com/BetaHuhn/electron-win-state')
Development Mode
During development it might be helpful to store the window size and position immediately after changing it and not just after closing the window. You can enable this functionality by setting dev
to true:
import WinState from 'electron-win-state'
const browserWindow = WinState.createBrowserWindow({
width: 800,
height: 600,
winState: {
dev: true
}
})
browserWindow.loadURL('https://github.com/BetaHuhn/electron-win-state')
Resetting the Window
If addMethods
is enabled (it is by default) a .resetWindowToDefault()
method will be added to the provided BrowserWindow and can be used to both reset the stored state, as well as resizing the window to it's defaults:
import WinState from 'electron-win-state'
const browserWindow = WinState.createBrowserWindow({
width: 800,
height: 600,
winState: {
dev: true
}
})
// Later
browserWindow.resetWindowToDefault()
This method could also be accessed anywhere else in your Electron app by getting the currently focused window:
const browserWindow = BrowserWindow.getFocusedWindow()
browserWindow.resetWindowToDefault()
Storing the frame option
You can optionally store the frame option as well. This might be useful if you want your users to enable or disable the window frame and store their choice.
If storeFrameOption
is enabled (or defaultFrame
is provided) the frame
or defaultFrame
option will be stored and can be later changed with the .setFramed()
method on the provided BrowserWindow (will be added if addMethods
is true).
You have to recreate the window for the
frame
option to take effect
import WinState from 'electron-win-state'
const browserWindow = WinState.createBrowserWindow({
width: 800,
height: 600,
frame: false,
winState: {
storeFrameOption: true
}
})
// Later
browserWindow.setFramed(true)
This method could also be accessed anywhere else in your Electron app by getting the currently focused window:
const browserWindow = BrowserWindow.getFocusedWindow()
browserWindow.setFramed(true)
Get stored values
You can access the restored window size and position with the winOptions
object:
const winState = new WinState({
defaultWidth: 800,
defaultHeight: 600,
defaultFrame: false
})
winState.winOptions // => { width: 1200, height: 700, x: 50, y: 105, frame: true }
You can get the stored values at any time using the added .getStoredWinOptions()
method on the BrowserWindow (only added if addMethods
is true):
import WinState from 'electron-win-state'
const browserWindow = WinState.createBrowserWindow({
winState: {
defaultWidth: 800,
defaultHeight: 600,
defaultFrame: false
}
})
browserWindow.getStoredWinOptions() // => { width: 1200, height: 700, x: 50, y: 105, frame: true }
💻 Development
Issues and PRs are very welcome!
- run
yarn lint
ornpm run lint
to run eslint. - run
yarn watch
ornpm run watch
to watch for changes. - run
yarn build
ornpm run build
to produce a compiled version in thelib
folder.
❔ About
This project was developed by me (@betahuhn) in my free time. If you want to support me:
Credit
This library uses the great electron-store by @sindresorhus under the hood and was inspired by electron-window-state and electron-boilerplate.
📄 License
Copyright 2021 Maximilian Schiller
This project is licensed under the MIT License - see the LICENSE file for details.