{"id":21215799,"url":"https://github.com/betahuhn/electron-win-state","last_synced_at":"2025-09-22T18:49:07.435Z","repository":{"id":36964115,"uuid":"375153926","full_name":"BetaHuhn/electron-win-state","owner":"BetaHuhn","description":"🖼️ :electron: Store and restore your Electron Window's Size and Position.","archived":false,"fork":false,"pushed_at":"2023-03-08T08:01:39.000Z","size":952,"stargazers_count":13,"open_issues_count":10,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-25T01:40:07.521Z","etag":null,"topics":["electron","typescript"],"latest_commit_sha":null,"homepage":"https://readme.fish/BetaHuhn/electron-win-state","language":"TypeScript","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/BetaHuhn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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},"funding":{"ko_fi":"betahuhn","github":"betahuhn"}},"created_at":"2021-06-08T21:49:40.000Z","updated_at":"2024-08-31T02:30:18.000Z","dependencies_parsed_at":"2024-06-21T03:52:43.188Z","dependency_job_id":"920e3b72-be3a-49d7-bb3c-0d91482fc3bf","html_url":"https://github.com/BetaHuhn/electron-win-state","commit_stats":{"total_commits":123,"total_committers":5,"mean_commits":24.6,"dds":"0.46341463414634143","last_synced_commit":"990bd2a928237254f434da946d40a924f4c9eb0b"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/BetaHuhn/electron-win-state","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BetaHuhn%2Felectron-win-state","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BetaHuhn%2Felectron-win-state/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BetaHuhn%2Felectron-win-state/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BetaHuhn%2Felectron-win-state/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BetaHuhn","download_url":"https://codeload.github.com/BetaHuhn/electron-win-state/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BetaHuhn%2Felectron-win-state/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264572976,"owners_count":23630379,"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","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","typescript"],"created_at":"2024-11-20T21:45:15.324Z","updated_at":"2025-09-22T18:49:07.375Z","avatar_url":"https://github.com/BetaHuhn.png","language":"TypeScript","funding_links":["https://ko-fi.com/betahuhn","https://github.com/sponsors/betahuhn","https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=394RTSBEEEFEE","https://ko-fi.com/F1F81S2RK"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \n# 🖼️💾 Electron Window State\n\n[![Node CI](https://github.com/BetaHuhn/electron-win-state/workflows/Node%20CI/badge.svg)](https://github.com/BetaHuhn/electron-win-state/actions?query=workflow%3A%22Node+CI%22) [![Release CI](https://github.com/BetaHuhn/electron-win-state/workflows/Release%20CI/badge.svg)](https://github.com/BetaHuhn/electron-win-state/actions?query=workflow%3A%22Release+CI%22) [![GitHub](https://img.shields.io/github/license/mashape/apistatus.svg)](https://github.com/BetaHuhn/electron-win-state/blob/master/LICENSE) ![David](https://img.shields.io/david/betahuhn/electron-win-state)\n\nStore and restore your Electron Window's Size and Position.\n\n\u003c/div\u003e\n\n## Features\n\n- 💾 **Persistent** - *persistently stores your Electron Window's size and position*\n- 🔌 **Easy integration** - *integrates easily with your existing BrowserWindow configuration*\n- 🔨 **Customization** - *customize the behaviour and the underlying [electron-store](https://github.com/sindresorhus/electron-store) instance*\n- 🖼️ **Frame option** - *you can [optionally](storing-the-frame-option) store the [frame](https://www.electronjs.org/docs/api/frameless-window#frameless-window) option as well*\n\n## 🚀 Get started\n\n```shell\nnpm install electron-win-state\n```\n\n*Requires Electron 11 or later*\n\n## 📚 Usage\n\nThe easiest way to use [electron-win-state](https://github.com/BetaHuhn/electron-win-state), is to add it as a wrapper around your normal [`BrowserWindow`](https://www.electronjs.org/docs/api/browser-window):\n\n```js\nimport WinState from 'electron-win-state'\n\nconst browserWindow = WinState.createBrowserWindow({\n\twidth: 800,\n\theight: 600,\n\t// your normal BrowserWindow options...\n})\n```\n\nThis will create a new [`BrowserWindow`](https://www.electronjs.org/docs/api/browser-window) with the provided options and store any changes once the window is closed.\n\nThats it! Your Electron app now has a persistent window! 🎉\n\n### Manually\n\nYou can also use [electron-win-state](https://github.com/BetaHuhn/electron-win-state) manually:\n\n```js\nconst winState = new WinState({ \n\tdefaultWidth: 800,\n\tdefaultHeight: 600,\n\t// other winState options, see below\n})\n\nconst browserWindow = new BrowserWindow({\n\t...winState.winOptions,\n\t// your normal BrowserWindow options...\n})\n\n// Attach the required event listeners\nwinState.manage(this.browserWindow)\n```\n\nWith `winState.winOptions` you have access to the restored size and position of the window: \n\n```js\nconsole.log(winState.winOptions) // =\u003e { width: 800, height: 600, x: 0, y: 0, frame: true }\n```\n\n## ⚙️ Options\n\nYou can customize the behaviour of [electron-win-state](https://github.com/BetaHuhn/electron-win-state) further, by passing an options object to `new WinState()` or by specifying a `winState` object when using `.createBrowserWindow()`:\n\n```js\nnew WinState({ \n\tdefaultWidth: 800,\n\tdefaultHeight: 600,\n\tdev: true,\n\taddMethods: true\n})\n```\n\nOr:\n\n```js\nWinState.createBrowserWindow({\n    winState: {\n\t\tdefaultWidth: 800,\n\t\tdefaultHeight: 600,\n\t\tdev: true,\n\t\taddMethods: true\n\t}\n})\n```\n\nOr:\n\n```js\nWinState.createBrowserWindow({\n\twidth: 800,\n\theight: 600,\n\twinState: {\n\t\tdev: true,\n\t\taddMethods: true\n\t}\n})\n```\n\nAll of these result in the same.\n\nHere are all the options [electron-win-state](https://github.com/BetaHuhn/electron-win-state) supports:\n\t\n| Name | Type | Description | Default |\n| ------------- | ------------- | ------------- | ------------- |\n| `defaultWidth` | `number` | The default width which will be used when no stored value was found | `800` |\n| `defaultHeight` | `number` | The default height which will be used when no stored value was found | `600` |\n| `defaultFrame` | `boolean` | The default value for the [frame](https://www.electronjs.org/docs/api/frameless-window#frameless-window) option when no stored value was found | `true` |\n| `storeFrameOption` | `boolean` | Store and restore the [frame](https://www.electronjs.org/docs/api/frameless-window#frameless-window) option (will be enabled automatically if `defaultFrame` is provided) | `false` |\n| `dev` | `boolean` | Enable development mode. Changes will be stored immediately after resizing or moving and not just after closing a window | `false` |\n| `addMethods` | `boolean` | Add the `.resetWindowToDefault()`, `.setFramed()` and `.getStoredWinOptions()` methods to the provided [BrowserWindow](https://www.electronjs.org/docs/api/browser-window) | `true` |\n| `electronStoreOptions` | [`object`](https://github.com/sindresorhus/electron-store#options) | Will be passed to the underlying [electron-store](https://github.com/sindresorhus/electron-store) instance | `{ name: 'window-state' }` |\n| `store` | [`instance`](https://github.com/sindresorhus/electron-store#instance) | An existing [electron-store](https://github.com/sindresorhus/electron-store) instance to use | n/a |\n\n## 📖 Examples\n\nHere are a few examples to help you get started!\n\n### Basic Example\n\nThis is the most basic example. A new [BrowserWindow](https://www.electronjs.org/docs/api/browser-window) will be created and the required event listeners will be attached automatically.\n\n```js\nimport WinState from 'electron-win-state'\n\nconst browserWindow = WinState.createBrowserWindow({\n\twidth: 800,\n\theight: 600\n})\n\nbrowserWindow.loadURL('https://github.com/BetaHuhn/electron-win-state')\n```\n\n---\n\n### Development Mode\n\nDuring 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:\n\n```js\nimport WinState from 'electron-win-state'\n\nconst browserWindow = WinState.createBrowserWindow({\n\twidth: 800,\n\theight: 600,\n\twinState: {\n\t\tdev: true\n\t}\n})\n\nbrowserWindow.loadURL('https://github.com/BetaHuhn/electron-win-state')\n```\n\n### Resetting the Window\n\nIf `addMethods` is enabled (it is by default) a `.resetWindowToDefault()` method will be added to the provided [BrowserWindow](https://www.electronjs.org/docs/api/browser-window) and can be used to both reset the stored state, as well as resizing the window to it's defaults:\n\n```js\nimport WinState from 'electron-win-state'\n\nconst browserWindow = WinState.createBrowserWindow({\n\twidth: 800,\n\theight: 600,\n\twinState: {\n\t\tdev: true\n\t}\n})\n\n// Later\nbrowserWindow.resetWindowToDefault()\n```\n\nThis method could also be accessed anywhere else in your Electron app by getting the currently focused window:\n\n```js\nconst browserWindow = BrowserWindow.getFocusedWindow()\nbrowserWindow.resetWindowToDefault()\n```\n\n---\n\n### Storing the frame option\n\nYou can optionally store the [frame](https://www.electronjs.org/docs/api/frameless-window#frameless-window) option as well. This might be useful if you want your users to enable or disable the window frame and store their choice.\n\nIf `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](https://www.electronjs.org/docs/api/browser-window) (will be added if `addMethods` is true).\n\n\u003e You have to recreate the window for the `frame` option to take effect\n\n```js\nimport WinState from 'electron-win-state'\n\nconst browserWindow = WinState.createBrowserWindow({\n\twidth: 800,\n\theight: 600,\n\tframe: false,\n\twinState: {\n\t\tstoreFrameOption: true\n\t}\n})\n\n// Later\nbrowserWindow.setFramed(true)\n```\n\nThis method could also be accessed anywhere else in your Electron app by getting the currently focused window:\n\n```js\nconst browserWindow = BrowserWindow.getFocusedWindow()\nbrowserWindow.setFramed(true)\n```\n\n---\n\n### Get stored values\n\nYou can access the restored window size and position with the `winOptions` object:\n\n```js\nconst winState = new WinState({ \n\tdefaultWidth: 800,\n\tdefaultHeight: 600,\n\tdefaultFrame: false\n})\n\nwinState.winOptions // =\u003e { width: 1200, height: 700, x: 50, y: 105, frame: true }\n```\n\nYou can get the stored values at any time using the added `.getStoredWinOptions()` method on the [BrowserWindow](https://www.electronjs.org/docs/api/browser-window) (only added if `addMethods` is true):\n\n```js\nimport WinState from 'electron-win-state'\n\nconst browserWindow = WinState.createBrowserWindow({\n\twinState: {\n\t\tdefaultWidth: 800,\n\t\tdefaultHeight: 600,\n\t\tdefaultFrame: false\n\t}\n})\n\nbrowserWindow.getStoredWinOptions() // =\u003e { width: 1200, height: 700, x: 50, y: 105, frame: true }\n```\n\n---\n\n## 💻 Development\n\nIssues and PRs are very welcome!\n\n- run `yarn lint` or `npm run lint` to run eslint.\n- run `yarn watch` or `npm run watch` to watch for changes.\n- run `yarn build` or `npm run build` to produce a compiled version in the `lib` folder.\n\n## ❔ About\n\nThis project was developed by me ([@betahuhn](https://github.com/BetaHuhn)) in my free time. If you want to support me:\n\n[![Donate via PayPal](https://img.shields.io/badge/paypal-donate-009cde.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=394RTSBEEEFEE)\n\n[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/F1F81S2RK)\n\n### Credit\n\nThis library uses the great [electron-store](https://github.com/sindresorhus/electron-store) by [@sindresorhus](https://github.com/sindresorhus) under the hood and was inspired by [electron-window-state](https://github.com/mawie81/electron-window-state) and [electron-boilerplate](https://github.com/szwacz/electron-boilerplate/blob/master/src/helpers/window.js).\n\n## 📄 License\n\nCopyright 2021 Maximilian Schiller\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbetahuhn%2Felectron-win-state","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbetahuhn%2Felectron-win-state","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbetahuhn%2Felectron-win-state/lists"}