fix: better shortcut registration and app icon matching on Wayland by mitchchn · Pull Request #49988 · electron/electron

mitchchn · 2026-03-01T21:44:45Z

Description of Change

(In this example, the fiddle's XDG app id is 'electron', its product name is a random string, and the suggested shortcut value is Ctrl+Shift+B, correctly reflecting what the caller asked for.)

This PR addresses two related issues on Wayland:

Global keyboard shortcuts: all Electron apps registered shortcuts to the same hardcoded ID,and they did not actually pass the requested accelerator to the shortcut portal.
App icons would sometimes show up as generic "W" placeholders in the taskbar, switcher, or title bar (see Fiddle in my screenshot).

Both issues have one of their underlying causes in common: the app's XDG identifier was usually not set to an appropriate value. (And if it was set, it wasn't always being respected by Chromium.)

Choosing a better default XDG app ID

Electron currently defaults to using the productName for its XDG identifier if no desktopName is provided by the developer. But a full product name with spaces like "Electron Fiddle" is not a valid ID, and even one-word product names like "Slack" usually have lowercase .desktop files, causing a mismatch out of the box.

I chose to use the app's executable name instead of productName as the default XDG app ID if one is not specified. On Linux, an app's executable name is conventionally* the same as its .desktop filename. e.g., Firefox has firefox.desktop, firefox as its command, and firefox as its XDG app ID. This same logic applies to many Electron apps which are currently missing their icons in some environments on Wayland: Electron Fiddle's exec name and .desktop file are both already electron-fiddle, so that should also be its default XDG app ID. Slack is another example: it already has a slack command and slack.desktop, and it would start resolving its icon correctly on Wayland if the default XDG app ID lined up.

While this heuristic won't work for every app, the executable name is a safer implicit default than a product name, and developers can continue to override the value by setting desktopName in package.json.

(*Technically, apps are supposed to use fully qualified domains for .desktop names and app IDs, but if this is important to you as a developer, you really should be setting desktopName manually!)

Fixing the shortcut portal

Now that we have workable IDs, I needed to patch Chromium to fix interactions with the shortcut portal. I decided to split this into two patches:

One patch to respect the Electron app's ID, which I doubt we can submit upstream.
Another patch to properly configure the shortcut trigger for the XDG portal.

I will upstream the second patch as Chromium will need it as well.

Checklist

PR description included
I have built and tested this PR
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: Global shortcuts can now be registered more reliably on Wayland using the globalShortcut API.

Fixed an issue where some apps had generic "W" icons on Wayland. This change impacts the default XDG application identifier. If you need this ID to have a stable value, set desktopName in package.json.

mitchchn · 2026-03-02T13:44:45Z

/request-review @codebytere

codebytere · 2026-03-02T14:34:27Z

+From: Mitchell Cohen <mitch.cohen@me.com>
+Date: Sun, 1 Mar 2026 16:22:00 -0500
+Subject: fix: set correct app id on Linux
+


We should also try to upstream this, yes?

Maybe? It's also a bit related to this patch you added and there might be a way to integrate them:
https://github.com/electron/electron/pull/49054/changes#diff-5b55d26d02a38ad2ac792d96c032afa436c1f660fd34d36189452c44586bb6d8

mitchchn · 2026-03-02T20:46:44Z

CL: https://chromium-review.googlesource.com/c/chromium/src/+/7620219

release-clerk · 2026-03-03T14:37:57Z

Release Notes Persisted

Global shortcuts can now be registered more reliably on Wayland using the globalShortcut API.

trop · 2026-03-03T14:38:04Z

I was unable to backport this PR to "40-x-y" cleanly;
you will need to perform this backport manually.

trop · 2026-03-03T14:38:08Z

I was unable to backport this PR to "39-x-y" cleanly;
you will need to perform this backport manually.

trop · 2026-03-03T14:38:33Z

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

Copilot

Pull request overview

Fixes Wayland-specific integration issues by improving how Electron derives the XDG application identifier (for icon/taskbar matching and portal identity) and by ensuring global shortcuts registered via the XDG portal carry the requested trigger/accelerator.

Changes:

Change the default Linux desktopName initialization to use the executable basename (instead of {app.name}.desktop).
Update global shortcut registration metadata to include the app name in the shortcut description.
Add two Chromium patches: one to respect CHROME_DESKTOP for app id/session naming, and one to pass preferred_trigger to the shortcut portal.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
shell/browser/api/electron_api_global_shortcut.cc	Updates shortcut description text to use the app’s name.
lib/browser/init.ts	Changes default Linux `desktopName` derivation to use `process.execPath`.
default_app/main.ts	Mirrors the `desktopName` default change for the default app loader path.
patches/chromium/fix_set_correct_app_id_on_linux.patch	Chromium patch to derive app id / session prefix from `CHROME_DESKTOP`.
patches/chromium/fix_pass_trigger_for_global_shortcuts_on_wayland.patch	Chromium patch to send `preferred_trigger` to the XDG shortcut portal based on the accelerator.
patches/chromium/.patches	Registers the new Chromium patches in Electron’s patch list.

Comments suppressed due to low confidence (1)

patches/chromium/fix_set_correct_app_id_on_linux.patch:71

This patch file looks truncated/malformed: it ends immediately after the #else in the GetSessionNamePrefix hunk, and the hunk header (@@ -61,6 +86,16 @@) no longer matches the number of lines actually present. As written, git apply / e sync is likely to fail with a “malformed patch” error. Please regenerate/export this patch so the full hunk is present and the hunk line counts match the content.

+
 #if BUILDFLAG(GOOGLE_CHROME_BRANDING)
   static constexpr std::string_view kSessionNamePrefix = "chrome";
 #else

Copilot · 2026-04-29T13:51:30Z

+Date: Sun, 1 Mar 2026 16:22:00 -0500
+Subject: fix: set correct app id on Linux
+
+Sets the Electron app's actual XDG app ID and DBus path instead of org.chromium.Chromium..


Minor typo in the patch description: there are two periods after “org.chromium.Chromium”.

Suggested change

Sets the Electron app's actual XDG app ID and DBus path instead of org.chromium.Chromium..

Sets the Electron app's actual XDG app ID and DBus path instead of org.chromium.Chromium.

Copilot · 2026-04-29T13:51:31Z

+        break;
+      case ui::VKEY_OEM_PERIOD:
+        trigger += "period";
+        break;


AcceleratorToXdgTrigger() returns an empty string for any unhandled KeyboardCode (via the default: return "" case). Electron accelerators support many additional keys (e.g. Plus, -, /, =, ;, [/], \, etc.), so those shortcuts will still be sent to the portal without a preferred_trigger, forcing manual user re-binding. Consider expanding the key mapping (or using a more general conversion helper) so common non-alphanumeric accelerators can still produce a valid XDG trigger string instead of silently falling back to "".

Suggested change

+ break;

+ break;

+ case ui::VKEY_OEM_MINUS:

+ trigger += "minus";

+ break;

+ case ui::VKEY_OEM_PLUS:

+ trigger += "equal";

+ break;

+ case ui::VKEY_OEM_2:

+ trigger += "slash";

+ break;

+ case ui::VKEY_OEM_5:

+ trigger += "backslash";

+ break;

+ case ui::VKEY_OEM_1:

+ trigger += "semicolon";

+ break;

+ case ui::VKEY_OEM_7:

+ trigger += "apostrophe";

+ break;

+ case ui::VKEY_OEM_4:

+ trigger += "bracketleft";

+ break;

+ case ui::VKEY_OEM_6:

+ trigger += "bracketright";

+ break;

+ case ui::VKEY_OEM_3:

+ trigger += "grave";

+ break;

Copilot · 2026-04-29T13:51:31Z

+// Set application's desktop name (Linux). These usually match the executable name,
+// so use it as the default to ensure the app gets the correct icon in the taskbar and application switcher.
+const desktopName = packageJson.desktopName || `${path.basename(process.execPath)}.desktop`;
+app.setDesktopName(desktopName);


This changes the default Linux desktopName from {app.name}.desktop to ${path.basename(process.execPath)}.desktop. There are API docs that still state the default is {app.name}.desktop (e.g. docs/api/base-window.md / docs/api/browser-window.md under win.setProgressBar). Please update the documentation to reflect the new default so developers know what value will be used when desktopName is omitted.

Copilot · 2026-04-29T13:51:32Z

+      // Set application's desktop name (Linux). These usually match the executable name,
+      // so use it as the default to ensure the app gets the correct icon in the taskbar and application switcher.
+      const desktopName = packageJson.desktopName || `${path.basename(process.execPath)}.desktop`;
+      app.setDesktopName(desktopName);


Same as lib/browser/init.ts: this changes the implicit default desktopName on Linux, but the docs still describe {app.name}.desktop as the default. Please update the relevant API docs (e.g. win.setProgressBar notes in docs/api/base-window.md / docs/api/browser-window.md) so the default matches what users read.

mitchchn added 3 commits March 1, 2026 14:48

fix: set default desktop name that matches exec name on linux

eefeaa7

chromium patches for global shortcuts

e682765

use app name for shortcut description

5f00c7b

mitchchn requested a review from a team as a code owner March 1, 2026 21:44

electron-cation Bot added the new-pr 🌱 PR opened recently label Mar 1, 2026

mitchchn changed the title ~~fix: better shortcut registration and icon matching on Wayland~~ fix: better shortcut registration and app icon matching on Wayland Mar 1, 2026

electron-issue-triage Bot requested a review from codebytere March 2, 2026 13:44

codebytere approved these changes Mar 2, 2026

View reviewed changes

codebytere added semver/patch backwards-compatible bug fixes target/39-x-y PR should also be added to the "39-x-y" branch. target/40-x-y PR should also be added to the "40-x-y" branch. target/41-x-y PR should also be added to the "41-x-y" branch. labels Mar 3, 2026

electron-cation Bot removed the new-pr 🌱 PR opened recently label Mar 3, 2026

codebytere merged commit 2f13d85 into electron:main Mar 3, 2026
138 of 141 checks passed

trop Bot removed the target/40-x-y PR should also be added to the "40-x-y" branch. label Mar 3, 2026

trop Bot added needs-manual-bp/40-x-y needs-manual-bp/39-x-y and removed target/39-x-y PR should also be added to the "39-x-y" branch. labels Mar 3, 2026

trop Bot mentioned this pull request Mar 3, 2026

fix: better shortcut registration and app icon matching on Wayland #50051

Merged

trop Bot added in-flight/41-x-y merged/41-x-y PR was merged to the "41-x-y" branch. and removed target/41-x-y PR should also be added to the "41-x-y" branch. in-flight/41-x-y labels Mar 3, 2026

ninjack-dev mentioned this pull request Apr 1, 2026

obsidian: Appears as "electron" After Launch NixOS/nixpkgs#505078

Closed

3 tasks

FelixLusseau mentioned this pull request Apr 10, 2026

[BUG/ENH] Add a key to package.json to prevent icon duplication and mismatch with Electron 41 aunetx/deezer-linux#229

Open

mitchchn mentioned this pull request Apr 29, 2026

Empty wm_class (Regression) #51375

Closed

3 tasks

ckerr requested a review from Copilot April 29, 2026 13:43

Copilot started reviewing on behalf of ckerr April 29, 2026 13:43 View session

Copilot AI reviewed Apr 29, 2026

View reviewed changes

mitchchn mentioned this pull request Apr 30, 2026

fix: set XDG app ID and WM_CLASS based on normalized app name #51424

Merged

7 tasks

emilioziniades mentioned this pull request May 4, 2026

feat: add desktopName to package.json IsmaelMartinez/teams-for-linux#2498

Closed

dsanders11 removed the needs-manual-bp/39-x-y label May 5, 2026

	Sets the Electron app's actual XDG app ID and DBus path instead of org.chromium.Chromium..
	Sets the Electron app's actual XDG app ID and DBus path instead of org.chromium.Chromium.

-+        break;
++        break;
++      case ui::VKEY_OEM_MINUS:
++        trigger += "minus";
++        break;
++      case ui::VKEY_OEM_PLUS:
++        trigger += "equal";
++        break;
++      case ui::VKEY_OEM_2:
++        trigger += "slash";
++        break;
++      case ui::VKEY_OEM_5:
++        trigger += "backslash";
++        break;
++      case ui::VKEY_OEM_1:
++        trigger += "semicolon";
++        break;
++      case ui::VKEY_OEM_7:
++        trigger += "apostrophe";
++        break;
++      case ui::VKEY_OEM_4:
++        trigger += "bracketleft";
++        break;
++      case ui::VKEY_OEM_6:
++        trigger += "bracketright";
++        break;
++      case ui::VKEY_OEM_3:
++        trigger += "grave";
++        break;

Conversation

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

Uh oh!

Description of Change

Choosing a better default XDG app ID

Fixing the shortcut portal

Checklist

Release Notes

Uh oh!

mitchchn commented Mar 2, 2026

Uh oh!

codebytere Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

mitchchn Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

mitchchn commented Mar 2, 2026

Uh oh!

Uh oh!

release-clerk Bot commented Mar 3, 2026

Uh oh!

trop Bot commented Mar 3, 2026

Uh oh!

trop Bot commented Mar 3, 2026

Uh oh!

trop Bot commented Mar 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mitchchn commented Mar 1, 2026 •

edited

Loading