feat: Shadows and CSD for frameless windows on Wayland by mitchchn · Pull Request #49295 · electron/electron

mitchchn · 2026-01-04T17:26:57Z

Description of Change

This PR is branched from and depends on: #49209, since it requires proper CSD bounds handling to work.

Adds GTK drop shadows and resize borders to frameless windows on Linux in native Wayland mode, including when WCO is in use.

Fixes #48570.
Fixes #36768.

Users can opt out of shadows and get a truly frameless window by setting hasShadow: false on the window constructor. (Currently, runtime changes have no effect.) In X11/Xwayland, frameless windows will continue to get server-side shadows as before.

Thought Process

Linux uses two classes for "frameless" views:

ClientFrameViewLinux, which is only used on Wayland when frame: true. It simulates a real window frame by drawing borders, shadows, and titlebars using GTK.
OpaqueFrameView, which is used on both X11 and Wayland. It draws frameless windows with optional WCO.

On X11 OpaqueFrameView gets window borders + shadows for free from the window manager. But Wayland is unable to provide specialized decorations to frameless windows, so if we want them, we have to draw our own.

ClientFrameViewLinux already had the ability to draw CSD. It also had all the layout code to compute various kinds of insets and bounds. So I factored out most of the layout logic into a new LinuxFrameLayout helper interface which has implementations for Wayland and X11 (or when decorations are not wanted). These can be used as delegates and selected at runtime.

This approach was inspired by Chromium, which also uses layout delegates for its frame views. I think it has quite a few advantages:

Any kind of frame can opt in or out of CSD on Linux.
Both of the existing frameless view classes have a lot less duplicate layout code, even compared to main.
The two Linux frameless view classes are now principally responsible for their different titlebars and unique concerns.
The tree host and window no longer needs to make decisions based on specific classes and can simply ask for the layout interface.

While the layout delegate pattern is currently only used on Linux in this PR, in the future it can also scale to other platforms and may be useful on Windows as well.

Checklist

PR description included and stakeholders cc'd
npm test passes
tests are changed or added
relevant API documentation, tutorials, and examples are updated and follow the documentation style guide
PR release notes describe the change in a way relevant to app developers, and are capitalized, punctuated, and past tense.

Release Notes

Notes: On Wayland (Linux), frameless windows now have GTK drop shadows and extended resize boundaries. To create fully frameless windows with no decorations, set hasShadow: false in the window constructor.

joshua-stone · 2026-01-04T21:49:35Z

Would this help address #45530, and would it do so in a way that doesn't require configuration on the user's part?

absidue · 2026-01-05T09:33:01Z

@mitchchn So that the linked issues get closed automatically when this is merged, you need to write "fixes" in front of each issue number, GitHub only picks up the first one, when you group them together the way that you have currently done it in the pull request description.

Broken format: fixes x, y
Correct format: fixes x, fixes y (or on separate lines so it is easier to read)

mitchchn · 2026-01-14T22:21:11Z

Tested a local build with VS Code. Here it is all in its glory:

…nto mitch/linux-layout

sedax90 · 2026-01-25T07:52:04Z

Is still in progress? Why is idle?

…l-bounds

…nto mitch/linux-layout

ckerr

Sorry for sitting on this for so long. This is good stuff.

release-clerk · 2026-02-20T00:53:16Z

Release Notes Persisted

On Wayland (Linux), frameless windows now have GTK drop shadows and extended resize boundaries. To create fully frameless windows with no decorations, set hasShadow: false in the window constructor.

* fix window sizing and content sizing on Linux when CSD is in use * fixed size constraints * layout helper * CSD shadows for frameless windows on Linux * simplify min/max size calculation * use base window size for min/max * respect HasShadow option * moved windows min/max size overrides * add newline at end of file * fix setting background color for frameless csd windows * fix wco positioning nad sizing to match prod * safety improvements Co-authored-by: Mitchell Cohen <mitch.cohen@me.com>

trop · 2026-02-20T00:53:30Z

I have automatically backported this PR to "41-x-y", please check out #49885

ckerr · 2026-02-20T00:54:43Z

Oh oof, I thought the API for this had been approved.

API LGTM for whatever that's worth. I'll ping @electron/wg-api here and in Slack about this accidental merge.

dominichayesferen · 2026-02-21T00:04:45Z

Congrats! 🎉

feat: Shadows and CSD for frameless windows on Wayland (#49295) * fix window sizing and content sizing on Linux when CSD is in use * fixed size constraints * layout helper * CSD shadows for frameless windows on Linux * simplify min/max size calculation * use base window size for min/max * respect HasShadow option * moved windows min/max size overrides * add newline at end of file * fix setting background color for frameless csd windows * fix wco positioning nad sizing to match prod * safety improvements Co-authored-by: trop[bot] <37223003+trop[bot]@users.noreply.github.com> Co-authored-by: Mitchell Cohen <mitch.cohen@me.com>

* fix window sizing and content sizing on Linux when CSD is in use * fixed size constraints * layout helper * CSD shadows for frameless windows on Linux * simplify min/max size calculation * use base window size for min/max * respect HasShadow option * moved windows min/max size overrides * add newline at end of file * fix setting background color for frameless csd windows * fix wco positioning nad sizing to match prod * safety improvements

mitchchn added 8 commits January 2, 2026 16:04

fix window sizing and content sizing on Linux when CSD is in use

e7d91d9

fixed size constraints

492651e

layout helper

531e38a

CSD shadows for frameless windows on Linux

2049506

simplify min/max size calculation

23d10ff

use base window size for min/max

719970c

synced with logical bounds changes

ae57e2c

respect HasShadow option

8e85609

electron-cation bot added the new-pr 🌱 PR opened recently label Jan 4, 2026

mitchchn changed the title ~~feat: Shadows and CSD for framless windows on Wayland~~ feat: Shadows and CSD for frameless windows on Wayland Jan 4, 2026

mitchchn added 3 commits January 4, 2026 13:28

moved windows min/max size overrides

0994c2c

Merge branch 'mitch/logical-bounds' into mitch/linux-layout

fde9174

add newline at end of file

d1cbf8f

This comment was marked as off-topic.

Sign in to view

ckerr requested review from ckerr January 5, 2026 21:13

ckerr added no-backport wayland labels Jan 5, 2026

electron-cation bot removed the new-pr 🌱 PR opened recently label Jan 11, 2026

sedax90 mentioned this pull request Jan 12, 2026

[GNOME Linux] No window decoration (shadow) if a window title bar style is custom microsoft/vscode#225073

Open

mitchchn added 2 commits January 14, 2026 17:19

fix setting background color for frameless csd windows

c04f1e5

fix wco positioning nad sizing to match prod

487c29c

Merge branch 'mitch/logical-bounds' of github.com:mitchchn/electron i…

168f283

…nto mitch/linux-layout

mitchchn added 2 commits January 25, 2026 14:57

Merge branch 'main' of github.com:electron/electron into mitch/logica…

e9cf4f5

…l-bounds

Merge branch 'mitch/logical-bounds' of github.com:mitchchn/electron i…

440d9c1

…nto mitch/linux-layout

mitchchn mentioned this pull request Feb 6, 2026

fix: accurate window sizing and support for content sizing on Linux/Wayland with CSD #49209

Merged

5 tasks

GoodbyeNJN mentioned this pull request Feb 8, 2026

Wayland下丢失窗口阴影 imsyy/SPlayer#803

Closed

5 tasks

nikwen added the target/41-x-y PR should also be added to the "41-x-y" branch. label Feb 17, 2026

mitchchn added 2 commits February 17, 2026 20:10

updated from main and fixed conflicts

68096c9

safety improvements

b7dd6e9

ckerr added the semver/minor backwards-compatible functionality label Feb 20, 2026

electron-cation bot added the api-review/requested 🗳 label Feb 20, 2026

ckerr removed api-review/requested 🗳 no-backport labels Feb 20, 2026

electron-cation bot added the api-review/requested 🗳 label Feb 20, 2026

ckerr approved these changes Feb 20, 2026

View reviewed changes

ckerr merged commit ea89ba5 into electron:main Feb 20, 2026
113 of 115 checks passed

trop bot mentioned this pull request Feb 20, 2026

feat: Shadows and CSD for frameless windows on Wayland #49885

Merged

trop bot added in-flight/41-x-y and removed target/41-x-y PR should also be added to the "41-x-y" branch. labels Feb 20, 2026

trop bot added merged/41-x-y PR was merged to the "41-x-y" branch. and removed in-flight/41-x-y labels Feb 25, 2026

mitchchn mentioned this pull request Mar 2, 2026

fix: improved the appearance of shadows and borders on frameless windows on Wayland #50007

Merged

6 tasks

georgexu99 mentioned this pull request Mar 10, 2026

docs: document Wayland frameless window shadow behaviour #50193

Merged

6 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Shadows and CSD for frameless windows on Wayland#49295

feat: Shadows and CSD for frameless windows on Wayland#49295
ckerr merged 19 commits intoelectron:mainfrom
mitchchn:mitch/linux-layout

mitchchn commented Jan 4, 2026 •

edited

Loading

Uh oh!

joshua-stone commented Jan 4, 2026

Uh oh!

This comment was marked as off-topic.

Uh oh!

absidue commented Jan 5, 2026 •

edited

Loading

Uh oh!

mitchchn commented Jan 14, 2026

Uh oh!

sedax90 commented Jan 25, 2026

Uh oh!

ckerr left a comment

Uh oh!

Uh oh!

release-clerk bot commented Feb 20, 2026

Uh oh!

trop bot commented Feb 20, 2026

Uh oh!

ckerr commented Feb 20, 2026

Uh oh!

dominichayesferen commented Feb 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

Conversation

mitchchn commented Jan 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of Change

Thought Process

Checklist

Release Notes

Uh oh!

joshua-stone commented Jan 4, 2026

Uh oh!

This comment was marked as off-topic.

Uh oh!

absidue commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mitchchn commented Jan 14, 2026

Uh oh!

sedax90 commented Jan 25, 2026

Uh oh!

ckerr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

release-clerk bot commented Feb 20, 2026

Uh oh!

trop bot commented Feb 20, 2026

Uh oh!

ckerr commented Feb 20, 2026

Uh oh!

dominichayesferen commented Feb 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

mitchchn commented Jan 4, 2026 •

edited

Loading

absidue commented Jan 5, 2026 •

edited

Loading