rfc: Save/Restore Window-State API #16

nilayarya · 2025-05-17T00:26:23Z

Note

This RFC is part of GSoC 2025

This proposal aims to implement a save/restore window state API for Electron by providing a simple but powerful configuration object windowStatePersistence that handles complex edge cases automatically. This approach offers a declarative way to configure window persistence behavior while maintaining flexibility for different application needs. The object would be optional in the BaseWindowConstructorOptions.

Rendered doc: https://github.com/nilayarya/rfcs/blob/main/text/0016-save-restore-window-state.md

Related: electron/electron#526

itsananderson

I typed up some comments while reviewing last week, but forgot to hit submit 🤦‍♂️

text/0013-save-restore-window-state.md

itsananderson · 2025-05-22T17:21:36Z

text/0013-save-restore-window-state.md

+- A window can never be restored out of reach. I am presuming no apps would want this behavior. `fallbackBehaviour` will take effect if the window is entirely off screen. We are still providing the option to relaunch in a minimized state.
+- If window (width, height) reopens on a different display and does not fit on screen auto adjust to fit and resave the value (even if allowOverflow=true). This would reduce the number of edge cases significantly and I highly doubt that any app would want to preserve an overflow when opened on a different display.
+- Not handling scaling as Windows, macOS, and Linux support multimonitor window scaling by default.
+- Not handling other `displayModes` such as split screen because it's innapropriate I believe. We can restore back to the same bounds in 'normal' mode. I've excluded 'normal' from the options for `displayMode` as it is the default.


Would this also include things like "Window Snapping"?

Snapping a window does not make the window enter any special displayMode on windows and linux. We can handle it as 'normal' state only. I've updated the RFC to reflect the same.

On macOS the 'tile window to the left/right of the screen' makes it enter fullscreen mode officially. We can treat it as a fullscreen state. If you think that's inappropriate we can restore it in a normal state to where it was before the split screen. This is something that needs to be finalized.

@electron/api-wg

nilayarya · 2025-06-05T10:15:44Z

text/0013-save-restore-window-state.md

+
+#### Developer-Facing Events
+
+I’m also considering emitting events such as: `will-save-window-state`, `saved-window-state`, `will-restore-window-state`, `restored-window-state`. However, I’m unsure about their practical usefulness for developers and hope to finalize them through this RFC.


@electron/api-wg any thoughts on these?

@electron/api-wg any thoughts on these?

If these events allow for intercepting and overriding the state save, I can see them being used to redirect the new state to other places. The same applies to reading the window state, as it could be read or loaded from a different source.

For example, in my comment on electron/electron#47425 (comment) (4th paragraph), I am thinking of saving the users' window states in the cloud and attempting to read them from there on window initialization. This way, their preferred window position would persist even across different machines and instances of the application executable. If these events allow for that use case, they would be very welcome.

Edit: If this is not possible, maybe it could be done by providing a loader and saver handler to windowStateRestoreOptions but if this is not planned to be supported as of now, I suppose it would complicate the API and implementation a lot. Flexibility is always good, but it may not be worth pursuing this at this stage of this RFC.

Edit 2: The option in my first edit seems very cumbersome. Maybe the will-save-window-state and saved-window-state can pass the data to be saved as a parameter to their handler? And also allow for intercepting and cancelling the save in the default format. Then, maybe the will-restore-window-state could restore the window saved with custom data if the event handler returns such custom data, while also allowing for the cancellation of the default behaviour? I imagine I could integrate cloud persistence of the window state on a per-user basis if these features were available.

Edit: If this is not possible, maybe it could be done by providing a loader and saver handler to windowStateRestoreOptions but if this is not planned to be supported as of now, I suppose it would complicate the API and implementation a lot. Flexibility is always good, but it may not be worth pursuing this at this stage of this RFC.

The issue with this is that const win = new BrowserWindow() is synchronous. Custom loader functions could introduce async operations during window construction. Also, Custom loader/saver handlers would completely defeat the purpose of having a declarative API.

Edit 2: The option in my first edit seems very cumbersome. Maybe the will-save-window-state and saved-window-state can pass the data to be saved as a parameter to their handler? And also allow for intercepting and cancelling the save in the default format. Then, maybe the will-restore-window-state could restore the window saved with custom data if the event handler returns such custom data, while also allowing for the cancellation of the default behaviour? I imagine I could integrate cloud persistence of the window state on a per-user basis if these features were available.

On second thought there isn't much utility for these events beyond just telemetry. Adding these events with the ability to intercept and modify saved values, add custom restoration logic, use a custom format would unnecessarily increase the implementation complexity and maintainability. Performance implications of running custom logic for hundreds of events per second during window manipulation needs to be considered.

We can definitely reconsider this upon further discussion. Thanks for the suggestion.

Let me know if you can think of any use case that cannot be accomplished via app.setWindowState() app.getWindowState()

For your cloud sync use case, a simpler approach might be for electron to provide an API like app.setWindowState([stateId], [stateObj]) that allows you to synchronously modify saved states before new BrowserWindow() initialization.
This would enable you to leverage electron's restoration logic for all the edge cases (display changes, bounds validation, etc.) rather than requiring you to reimplement that complexity yourself.

For saving to the cloud you could use app.getWindowState([stateId]) at your leisure.

I agree that the API should be kept as simple as possible, while allowing versatility.

For your cloud sync use case, a simpler approach might be for electron to provide an API like app.setWindowState([stateId], [stateObj]) that allows you to synchronously modify saved states before new BrowserWindow() initialization.

Would app.setWindowState([stateId], [stateObj]) overwrite the locally saved window states for the specific stateIds provided? This would make it possible to support my use case, because I could pull the latest state from the cloud and update it locally upon each app launch.

For saving to the cloud you could use app.getWindowState([stateId]) at your leisure.

I would suggest having a separate BrowserWindow.getState() or BrowserWindow.getCurrentState() that avoids reading the window state from the disk and returns the BrowserWindow's current state computed directly from memory. This would avoid a file read if I understand correctly, right?

Furthermore, this API would make the events you suggest very useful for my cloud use case. It would enable getting the new window state via BrowserWindow.getState() and pushing it to the cloud only when will-save-window-state fires (provided that BrowserWindow.getState() would return the same state that will be saved when will-save-window-state fires).

Having will-save-window-state would allow for 1) intercepting the new state even if, for any reason, the file write fails and 2) avoid adding handlers to the resize and move events, which fire very often when the window is moving and need manual debouncing to avoid performance issues (I've faced this in my JS soultion, handling it using a setTimeout as in electron/electron#47425 (comment)).

While the events would mainly serve for telemetry purposes, I suppose other developers who want to do quirky things like my cloud use case will find them useful in other contexts. I'd suggest keeping them unless they add complexity that is a maintenance burden.

I would suggest having a separate BrowserWindow.getState() or BrowserWindow.getCurrentState() that avoids reading the window state from the disk and returns the BrowserWindow's current state computed directly from memory. This would avoid a file read if I understand correctly, right?

Yes, it would avoid a file read. BrowserWindow.getState() or BrowserWindow.getCurrentState() are planned but not finalized yet.

While the events would mainly serve for telemetry purposes, I suppose other developers who want to do quirky things like my cloud use case will find them useful in other contexts. I'd suggest keeping them unless they add complexity that is a maintenance burden.

Implementation complexity and maintenance for these events should be fine. I've added them to the rfc.

text/0013-save-restore-window-state.md

nilayarya · 2025-06-05T11:19:53Z

text/0013-save-restore-window-state.md

+- A window can never be restored out of reach. I am presuming no apps would want this behavior. `fallbackBehaviour` will take effect if the window is entirely off screen. We are still providing the option to relaunch in a minimized state.
+- If window (width, height) reopens on a different display and does not fit on screen auto adjust to fit and resave the value (even if allowOverflow=true). This would reduce the number of edge cases significantly and I highly doubt that any app would want to preserve an overflow when opened on a different display.
+- Not handling scaling as Windows, macOS, and Linux support multimonitor window scaling by default.
+- Not handling other `displayModes` such as split screen because it's innapropriate I believe. We can restore back to the same bounds in 'normal' mode. I've excluded 'normal' from the options for `displayMode` as it is the default.


Snapping a window does not make the window enter any special displayMode on windows and linux. We can handle it as 'normal' state only. I've updated the RFC to reflect the same.

On macOS the 'tile window to the left/right of the screen' makes it enter fullscreen mode officially. We can treat it as a fullscreen state. If you think that's inappropriate we can restore it in a normal state to where it was before the split screen. This is something that needs to be finalized.

nilayarya · 2025-06-05T11:20:14Z

text/0013-save-restore-window-state.md

+- A window can never be restored out of reach. I am presuming no apps would want this behavior. `fallbackBehaviour` will take effect if the window is entirely off screen. We are still providing the option to relaunch in a minimized state.
+- If window (width, height) reopens on a different display and does not fit on screen auto adjust to fit and resave the value (even if allowOverflow=true). This would reduce the number of edge cases significantly and I highly doubt that any app would want to preserve an overflow when opened on a different display.
+- Not handling scaling as Windows, macOS, and Linux support multimonitor window scaling by default.
+- Not handling other `displayModes` such as split screen because it's innapropriate I believe. We can restore back to the same bounds in 'normal' mode. I've excluded 'normal' from the options for `displayMode` as it is the default.


@electron/api-wg

TheOneTheOnlyJJ · 2025-06-17T19:00:46Z

I'm not trying to be disruptive here, but after giving my proposed cloud sync use case some thought, I would like to put forward a few ideas, based on my opinions of how such a use case (and other potential non-standard use cases) could be supported most cleanly.

Would it be possible for BrowserWindow to accept a full window state object directly, in addition to the proposed stateId? This would let developers load state from custom sources (like the cloud) before constructing the window, while still allowing Electron to run its position restoration logic.

Alternatively, the window state loading could be fully decoupled into a dedicated API (app.getWindowState([stateId])), allowing developers to implement custom loaders. The constructor would then accept only a window state object, which would be validated and corrected as usual during the window creation process. To skip local persistence in these cases, developers could pass stateId: null (or undefined for easily having the default BrowserWindow constructor not persist the state).

To complete this flow, two instance-level events could be added.
A new state-adjusted event could be emitted when the initial window state object passed to the BrowserWindow constructor is modified by Electron’s internal restoration logic (to avoid overflow or off-screen placement).
Separately, a new state-updated event could be emitted whenever the window state changes due to user or programmatic actions (such as moving or resizing) and would normally be persisted. If stateId is set to null (not persisting the state on disk with the default API proposed as of now), this event would allow developers to handle custom persistence by calling BrowserWindow.getState() and syncing the result to the cloud.

EDIT: This new state-updated event I proposed is functionally equivalent to will-save-window-state, provided it fires even when the window state should not be persisted for that specific window (stateId: null or undefined).

What I try to achieve with these proposals is the ability to pass the window state to a new window and to get it for external saving, when it is updated, by completely bypassing the local JSON file persistence functionality. The current way the API is proposed would not allow for that and would require additional code to clean up window states periodically from disk.

I'm eager to hear your feedback and opinions.

nilayarya · 2025-06-18T07:47:04Z

I'm not trying to be disruptive here, but after giving my proposed cloud sync use case some thought, I would like to put forward a few ideas, based on my opinions of how such a use case (and other potential non-standard use cases) could be supported most cleanly.

Would it be possible for BrowserWindow to accept a full window state object directly, in addition to the proposed stateId? This would let developers load state from custom sources (like the cloud) before constructing the window, while still allowing Electron to run its position restoration logic.

This can be considered as an alternative to app.setWindowState([stateObj]).

Alternatively, the window state loading could be fully decoupled into a dedicated API (app.getWindowState([stateId])), allowing developers to implement custom loaders. The constructor would then accept only a window state object, which would be validated and corrected as usual during window creation. To skip local persistence in these cases, developers could simply pass stateId: null.

To skip local persistence developers can skip passing the windowStateRestoreOptions object entirely.

To complete this flow, two instance-level events could be added. A new state-adjusted event could be emitted when the initial window state object passed to the BrowserWindow constructor is modified by Electron’s internal restoration logic (to avoid overflow or off-screen placement). Separately, a new state-updated event could be emitted whenever the window state changes due to user or programmatic actions (such as moving or resizing) and would normally be persisted. If stateId is set to null (not persisting the state on disk with the default API proposed as of now), this event would allow developers to handle custom persistence by calling BrowserWindow.getState() and syncing the result to the cloud.

This can be moved to future possibilities.

TheOneTheOnlyJJ · 2025-06-18T08:05:05Z

This can be considered as an alternative to app.setWindowState([stateObj]).

But I suppose app.setWindowState([stateObj]), as it is right now, is doing a write to disk of the passed state object.
If this is the case, passing the window state object to the window as an argument directly is different because it would not do a file write.

To skip local persistence developers can skip passing the windowStateRestoreOptions object entirely.

While this is true, setting the window position manually with state from an external source would bypass the proposed repositioning algorithm that avoids overflow and excessive clipping.
Could this window state correction algorithm be exposed with its own API, something like app.adjustWindowState([windowState])?
If this were exposed, it would allow getting the state object from an external source and properly adjusting it to avoid all the edge cases mentioned in the discussions until now.
It may be a little cumbersome to map the state object data to the different window APIs to set the size, position, maximized/minimized/fullscreen/kiosk mode, but that is not a real problem.

This can be moved to future possibilities.

Yes, but is will-save-window-state intended to be fired when state persistence is disabled?
The name of the event does not suggest that. this is why I suggested the new event to be named as state-updated, because it does not imply that it will be persisted.

If state persistence is disabled (by not passing the windowStateRestoreOptions object) and this event does not fire, then I cannot know when new state should be handled.

If there were a way to add a callback to the moment the window would normally persist the state (even when it does not do it), it could be intercepted by a user function and processed further (i.e., sent to the cloud).

TheOneTheOnlyJJ · 2025-06-18T08:39:27Z

I just noticed that will-save-window-state can be prevented with e.preventDefault(), per your latest commit. This is amazing, it's exactly the interception and redirection hook I've been looking for.

All that is left is the ability to have the state passed to/used by the window be read from any source rather than the local disk, thus my initial suggestion to allow passing the state directly to the window, avoiding app.setWindowState([stateObj]).

I feel like I'm disrupting your work with my specific, non-standard use case, and I don't want to impede the development of this feature.

As such, I will sum up my final ideas as concisely as possible here:

The ability to have the preventable will-save-window-state (maybe named state-updated?) be emitted even when not passing the windowStateRestoreOptions object to the window. This is the equivalent of intercepting the disk write and redirecting the state to an external destination. This would avoid listening for the move and resize events, which fire very often and cause real performance issues if not handled properly with a setTimeout. Maybe state-updated could be fired always, and will-save-window-state could fire specifically when the window was passed windowStateRestoreOptions in its constructor.
The ability to invoke the position/window state adjustment algorithm (that avoids overflow and excessive clipping) on arbitrary window state objects (such as those read/fetched from external sources). This would make it possible to avoid passing windowStateRestoreOptions object to the window while still enjoying the benefits of edge case correction. This API could be named app.adjustWindowState([windowState]) or something similar.

With just these 2 features, non-standard use cases such as mine could be supported while avoiding file reads and writes completely. For example, my cloud sync use case could fetch the window state from the cloud, adjust it using app.adjustWindowState([windowState]), then map it to the desired BrowserWindow instance after its initialisation, using the current APIs for setting the window size and position (could be further enhanced by having the BrowserWindow accept an initialWindowState prop that does not imply persistence), and have state updates pushed to the cloud by adding a hook to the state-updated event. This would completely avoid writing or reading the window state to/from disk, maintaining the best performance possible.

I hope you don't mind my comments, I'm just trying to help make this feature as flexible as possible, the best I can.

text/0013-save-restore-window-state.md

samuelmaddock · 2025-08-28T17:10:48Z

text/0016-save-restore-window-state.md

+// Clear the entire saved state for the window
+const success = BaseWindow.clearState('#1230');
+console.log(success) // true if state was successfully cleared
+```


Can we add clarification around when this might not be successful?

Maybe better to be clearWindowStatePersistence

Hey guys, this API needs to be updated to reflect the current implementation here https://github.com/electron/electron/pull/47781/files#diff-f9f17ef8ca27777eaf90d9632c1e359effa0a710cec6bbbab55ddbee1f217a31R390 for reference

Does this sound reasonable to you guys? The API is actually called BaseWindow.clearWindowState(windowName) and it logs some warnings if window state isn't cleared.

state is an ambiguous term so I think it'd be best to be specific. I agree with @reitowo's suggestion to include some variant of "persistence" in the name so it's clear what kind of state this is related to.

Sure! will update this to BaseWindow.clearWindowStatePersistence(name) 👍

@samuelmaddock @reitowo do you guys think BaseWindow.clearSavedState(name) sounds better?

Looks better, I also suggest clearPersistedState

We'll also have to rename the restored-window-state event to match, so either restored-persisted-state or restored-saved-state.

Note: There are some other proposed events with save in them in this RFC, such as saved-window-state, will-save-window-state that might need a more consistent name if we end up going with clearPersistedState

text/0016-save-restore-window-state.md

reitowo · 2025-09-04T09:42:30Z

text/0016-save-restore-window-state.md

+
+### BaseWindowConstructorOptions
+
+* `name` string (optional) - A unique identifier for the window, used internally by Electron to enable features such as state persistence. Each window must have a distinct name. It can only be reused after the corresponding window has been destroyed. An error is thrown if the name is already in use. This is not the visible title shown to users on the title bar.


I still think name is not the best option, since similar names are in electron but without uniqueness

Thanks for pointing this out @reitowo! name doesn't imply uniqueness so uniqueName seems like the best candidate for now (as suggested by @itsananderson)

Linking previous discussions here so we have everything in one place.
https://github.com/electron/electron/pull/47764/files#r2260998113

I still think name is not the best option, since similar names are in electron but without uniqueness

Should we leave it up to the developers to not confuse Electron.BrowserWindow.name to be Electron.WebFrameMain.name or something similar, despite the description for the property being well documented?

I'm also presuming the description will show up in most IDEs the same way it shows up in your example image, so that should help with the confusion.

Co-authored-by: Erick Zhao <erick@hotmail.ca>

nilayarya requested a review from a team as a code owner May 17, 2025 00:26

itsananderson added the pending-review Waiting for reviewers to give feedback on the PR specifications label May 22, 2025

itsananderson reviewed May 29, 2025

View reviewed changes

nilayarya commented Jun 5, 2025

View reviewed changes

nilayarya mentioned this pull request Jun 13, 2025

feat: save window state electron/electron#47425

Merged

4 tasks

nilayarya requested review from itsananderson and TheOneTheOnlyJJ June 18, 2025 15:27

erickzhao reviewed Jun 19, 2025

View reviewed changes

samuelmaddock reviewed Aug 28, 2025

View reviewed changes

erickzhao added pending-changes Waiting for changes from the PR author based on feedback given and removed pending-review Waiting for reviewers to give feedback on the PR specifications labels Aug 28, 2025

erickzhao reviewed Aug 28, 2025

View reviewed changes

text/0016-save-restore-window-state.md Outdated Show resolved Hide resolved

reitowo reviewed Sep 4, 2025

View reviewed changes

nilayarya requested review from samuelmaddock, reitowo and erickzhao September 4, 2025 18:57

erickzhao added pending-review Waiting for reviewers to give feedback on the PR specifications and removed pending-changes Waiting for changes from the PR author based on feedback given labels Sep 11, 2025

erickzhao approved these changes Sep 11, 2025

View reviewed changes

nilayarya force-pushed the main branch 2 times, most recently from 34e79ad to 58c6001 Compare October 4, 2025 05:48

nilayarya and others added 26 commits October 4, 2025 19:37

rfc: Save/Restore Window-State API

9a1c16b

update: smaller api surface

06fb244

future possibilities

f882e8b

update: future possibilities

344e75c

add api for app.clearWindowState

9ef5771

don't save kiosk and minimized displayModes

9555e95

don't save display scale and resolution

2bd4002

add api for app.setWindowState()

7ec84c8

update event emitters

45e3705

Update text/0013-save-restore-window-state.md

4802bda

Co-authored-by: Erick Zhao <erick@hotmail.ca>

update clearWindowState and remove get/setWindowState

64b6bd8

update rfc file name

960a99c

update api surface to have name and windowStatePersistence

27d4b48

improve guide level explanation

411d7ff

updates to reflect the new api surface

469350d

unresolved questions and future possibilities

2628ed9

better formatting

453ae58

better formatting

1ad2b0f

better formatting

a5cb505

Apply suggestion from @erickzhao

4d6caf8

Co-authored-by: Erick Zhao <erick@hotmail.ca>

update docs for name and clearWindowState

47d4996

update API surface for win.restorePreferences([options])

a0141f3

update clearWindowState to clearPersistedState

901a7e9

better formatting

ef3d3e2

add docs for no display scenario

90bf523

update event names to reduce ambiguity

af0ad62

nilayarya force-pushed the main branch from 58c6001 to af0ad62 Compare October 4, 2025 23:38

erickzhao merged commit de50c96 into electron:main Oct 6, 2025
3 checks passed


		#### Developer-Facing Events

		I’m also considering emitting events such as: `will-save-window-state`, `saved-window-state`, `will-restore-window-state`, `restored-window-state`. However, I’m unsure about their practical usefulness for developers and hope to finalize them through this RFC.


		### BaseWindowConstructorOptions

		* `name` string (optional) - A unique identifier for the window, used internally by Electron to enable features such as state persistence. Each window must have a distinct name. It can only be reused after the corresponding window has been destroyed. An error is thrown if the name is already in use. This is not the visible title shown to users on the title bar.

rfc: Save/Restore Window-State API #16

rfc: Save/Restore Window-State API #16

Uh oh!

Conversation

nilayarya commented May 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

itsananderson left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

itsananderson May 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nilayarya Jun 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TheOneTheOnlyJJ Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nilayarya Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nilayarya Jun 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TheOneTheOnlyJJ commented Jun 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nilayarya commented Jun 18, 2025

Uh oh!

TheOneTheOnlyJJ commented Jun 18, 2025

Uh oh!

TheOneTheOnlyJJ commented Jun 18, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nilayarya commented May 17, 2025 •

edited

Loading

itsananderson May 22, 2025 •

edited

Loading

nilayarya Jun 5, 2025 •

edited

Loading

TheOneTheOnlyJJ Jun 13, 2025 •

edited

Loading

nilayarya Jun 13, 2025 •

edited

Loading

nilayarya Jun 5, 2025 •

edited

Loading

TheOneTheOnlyJJ commented Jun 17, 2025 •

edited

Loading

nilayarya Sep 4, 2025 •

edited

Loading