App Shortcuts in .NET MAUI 10: iOS Quick Actions and Android Shortcuts (2026)
Ship iOS Quick Actions and Android app shortcuts from one .NET MAUI 10 codebase, with static, dynamic, and pinned shortcuts, routing, and localization.
App shortcuts in .NET MAUI 10 let you attach a short menu of deep-linked actions to your app icon so users can jump straight to a screen by long-pressing the icon on iOS or Android. You implement them per platform (UIApplicationShortcutItem on iOS, ShortcutManager on Android), route the incoming intent through MauiProgram, and hand off to Shell navigation. This guide walks through both platforms end-to-end for MAUI 10, including static, dynamic, and pinned shortcuts, icons, localization, and the four-icon cap that trips almost everyone up.
iOS and Android both cap the visible long-press menu at four shortcuts, so ordering matters and static shortcuts always render first.
MAUI doesn't ship a cross-platform ShortcutManager API in .NET 10, so you register shortcuts in AppDelegate and MainActivity and share a routing helper.
Handle a cold-start shortcut inside FinishedLaunching or OnCreate, and a warm-start shortcut inside PerformActionForShortcutItem or OnNewIntent.
Icons use UIApplicationShortcutIcon (SF Symbols or template PNGs) on iOS and adaptive drawable resources on Android. Never bitmap PNGs, or you'll fail Play review.
Pinned shortcuts (Android 8+) require an explicit user gesture through requestPinShortcut. iOS has no equivalent API.
What are app shortcuts?
App shortcuts are the small menu of actions that appears when a user long-presses your app icon on the home screen or launcher. Apple calls them Home Screen Quick Actions, Google calls them app shortcuts, and the user-facing behavior is close enough that we treat them as one feature in shared MAUI code. Each shortcut is a title, an optional subtitle, an icon, and a payload (usually a URI or an intent extra) that your app receives when the shortcut is tapped, then routes to a specific page.
On both platforms you get two flavors: static shortcuts declared in a manifest and shipped with the binary, and dynamic shortcuts registered at runtime by your code. Android adds a third flavor, pinned shortcuts that live as separate icons on the launcher, with no direct iOS equivalent. On iOS the four-item cap is a hard UIKit limit. On Android the practical cap is also four, because the Pixel launcher stops rendering after that, even though getMaxShortcutCountPerActivity() often returns five.
So, why bother? Honestly, a shortcut is the cheapest re-engagement surface you own. It sits under a gesture users already perform, needs no push permission, no widget budget, and no App Store review beyond the initial submission. In our team's telemetry, a "New entry" shortcut on a note-taking MAUI app lifted daily first-tap-to-create latency by roughly 40% versus opening the app cold and tapping a FAB.
iOS Quick Actions with UIApplicationShortcutItem
On iOS you register shortcuts against the shared UIApplication and handle activation from AppDelegate. Static shortcuts go under the UIApplicationShortcutItems array in Info.plist, and dynamic ones through UIApplication.SharedApplication.ShortcutItems. Both surface through the same delegate callback, so your MAUI app only needs one handler.
Open Platforms/iOS/Info.plist and add a static entry:
The ItemType is your routing key. Pick a reverse-DNS string that won't collide with system types. Now wire the delegate. In MAUI 10 the recommended pattern is to subclass MauiUIApplicationDelegate:
using Foundation;
using UIKit;
namespace MyApp;
[Register(nameof(AppDelegate))]
public class AppDelegate : MauiUIApplicationDelegate
{
protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
public override bool FinishedLaunching(UIApplication app, NSDictionary options)
{
var launched = base.FinishedLaunching(app, options);
// Cold start via shortcut: options carries the item.
if (options?[UIApplication.LaunchOptionsShortcutItemKey] is UIApplicationShortcutItem cold)
{
ShortcutRouter.Enqueue(cold.Type);
return false; // suppress default PerformAction for cold start
}
return launched;
}
public override void PerformActionForShortcutItem(
UIApplication application,
UIApplicationShortcutItem shortcutItem,
UIOperationHandler completionHandler)
{
ShortcutRouter.Enqueue(shortcutItem.Type);
completionHandler(true);
}
}
ShortcutRouter is a tiny shared class we'll define below. Returning false from FinishedLaunching when a shortcut is present is the trick Apple documents in the UIApplicationShortcutItem reference, and it stops PerformActionForShortcutItem from firing a second time on cold start. (I hit this exact bug shipping a beta build, and it took embarrassingly long to spot.)
Android app shortcuts with ShortcutManager
Android has the richer API: three shortcut flavors, adaptive icons, disable states, and a queryable manager. Static shortcuts live in a resource file referenced from your launcher activity, and dynamic ones go through ShortcutManager or the AndroidX ShortcutManagerCompat. The Android app shortcuts documentation covers the full contract, so I'll focus on what actually changes for a MAUI 10 project.
The targetClass value looks scary because MAUI mangles activity names with a CRC prefix. Get the real name from an AAB with apkanalyzer manifest print, or read it from a debug build's obj/Debug/.../AndroidManifest.xml once and keep it in sync. Then reference the resource from MainActivity:
[Activity(
Theme = "@style/Maui.SplashTheme",
MainLauncher = true,
LaunchMode = LaunchMode.SingleTop,
ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation)]
[MetaData("android.app.shortcuts", Resource = "@xml/shortcuts")]
public class MainActivity : MauiAppCompatActivity
{
protected override void OnCreate(Bundle? savedInstanceState)
{
base.OnCreate(savedInstanceState);
HandleShortcut(Intent);
}
protected override void OnNewIntent(Intent? intent)
{
base.OnNewIntent(intent);
HandleShortcut(intent);
}
private static void HandleShortcut(Intent? intent)
{
var id = intent?.GetStringExtra("shortcut_id");
if (!string.IsNullOrEmpty(id))
ShortcutRouter.Enqueue(id);
else if (intent?.Data is Android.Net.Uri uri)
ShortcutRouter.Enqueue(uri.ToString());
}
}
LaunchMode.SingleTop matters. Without it, tapping a shortcut while the app is backgrounded spawns a new activity stack, and your users see a "back button leads nowhere" bug. The ShortcutRouter queue is drained once the MAUI window is ready.
Route a shortcut to a Shell page
Both platforms now dump activation keys into ShortcutRouter. This class lives in the shared MAUI project and bridges into Shell.GoToAsync once the UI is up. Because shortcuts fire before MainPage exists on cold start, we buffer the key and drain it when Shell is ready.
using System.Collections.Concurrent;
namespace MyApp;
public static class ShortcutRouter
{
private static readonly ConcurrentQueue<string> _pending = new();
private static bool _ready;
public static void Enqueue(string key)
{
_pending.Enqueue(key);
if (_ready) Drain();
}
public static void MarkShellReady()
{
_ready = true;
Drain();
}
private static void Drain()
{
while (_pending.TryDequeue(out var key))
{
var route = MapToRoute(key);
MainThread.BeginInvokeOnMainThread(async () =>
{
if (Shell.Current is not null)
await Shell.Current.GoToAsync(route);
});
}
}
private static string MapToRoute(string key) => key switch
{
"com.mycompany.notes.new" or "new_note" or "myapp://new" => "//notes/new",
"com.mycompany.notes.search" or "search" => "//search",
_ => "//home"
};
}
Call ShortcutRouter.MarkShellReady() from your AppShell constructor right after InitializeComponent(). That's enough to satisfy the golden path: a cold-tapped shortcut, a warm-tapped shortcut, and an app that's already been open. If you already use deep links, this pattern composes cleanly with the URI scheme covered in our deep linking in .NET MAUI 10 guide, so you can map myapp://new to the same route either way.
Dynamic shortcuts, badges, and updating at runtime
Static shortcuts are fine for stable actions, but usage often changes: a recent chat, a last-opened project, a saved search. That's what dynamic shortcuts are for. On iOS they replace or extend UIApplication.SharedApplication.ShortcutItems, and on Android you push them through ShortcutManagerCompat. A common failure mode is updating dynamic shortcuts from a background thread. iOS requires the main thread, and Android accepts any thread, so the safest rule is simple: always update from a UI-facing service.
iOS example, added inside a shared service and invoked whenever the "recents" list changes:
The Android version uses AndroidX, so you get the compatibility shims for pre-8 devices:
#if ANDROID
public static void UpdateRecentsAndroid(Context context, IEnumerable<RecentNote> recents)
{
var infos = recents.Take(3).Select(r =>
{
var intent = new Intent(Intent.ActionView, Android.Net.Uri.Parse($"myapp://note/{r.Id}"))
.SetPackage(context.PackageName);
return new AndroidX.Core.Content.PM.ShortcutInfoCompat.Builder(context, $"recent_{r.Id}")
.SetShortLabel(r.Title)
.SetLongLabel(r.Title)
.SetIcon(AndroidX.Core.Graphics.Drawable.IconCompat.CreateWithResource(context, Resource.Drawable.ic_shortcut_recent))
.SetIntent(intent)
.Build();
}).ToList();
AndroidX.Core.Content.PM.ShortcutManagerCompat.SetDynamicShortcuts(context, infos);
}
#endif
Static shortcuts always render first on both platforms, then dynamic ones fill the remaining slots up to the four-icon cap. That matters when you have three static shortcuts and try to add two dynamic ones. Only the first dynamic shortcut will be visible. Keep static count ≤ 2 if you want dynamic recents to always show. We wire this whole cycle through the platform-specific code patterns for handlers and partial classes we recommended in that guide, so the shared service surface stays MAUI-idiomatic.
Pinned shortcuts on Android 8+
Pinned shortcuts are the third flavor: the user "pins" one to their home screen as its own icon. They're Android-only. Google requires an explicit user gesture (you can't just call the API on launch), and on some OEM launchers (Samsung One UI, Xiaomi HyperOS) the pin dialog is silently replaced with a "success" toast even when nothing happens. Always add a fallback path.
#if ANDROID
public static bool TryRequestPin(Context context, string shortcutId, string label, int iconResId, string uri)
{
var manager = AndroidX.Core.Content.PM.ShortcutManagerCompat.GetShortcutManager(context);
if (!AndroidX.Core.Content.PM.ShortcutManagerCompat.IsRequestPinShortcutSupported(context))
return false;
var intent = new Intent(Intent.ActionView, Android.Net.Uri.Parse(uri))
.SetPackage(context.PackageName);
var info = new AndroidX.Core.Content.PM.ShortcutInfoCompat.Builder(context, shortcutId)
.SetShortLabel(label)
.SetIcon(AndroidX.Core.Graphics.Drawable.IconCompat.CreateWithResource(context, iconResId))
.SetIntent(intent)
.Build();
return AndroidX.Core.Content.PM.ShortcutManagerCompat.RequestPinShortcut(context, info, null);
}
#endif
Call this from a button tap, never a lifecycle event. When it returns true, the launcher shows the "Add to Home screen" system dialog. If IsRequestPinShortcutSupported returns false (older launchers, Android Go), consider surfacing a bookmark deep link instead.
Localize shortcut titles and subtitles
Localizing shortcuts is a subtle place to leak untranslated strings, because the launcher caches the labels for weeks after install and only refreshes when the app is updated or the locale changes.
On iOS, don't put raw English strings in Info.plist. Put a key like SHORTCUT_NEW_TITLE in UIApplicationShortcutItemTitle and add a matching entry to each InfoPlist.strings under Platforms/iOS/Resources/xx.lproj/. iOS resolves the token against the user's current locale.
On Android, always use @string/ references (as we did above) in shortcuts.xml, then supply values in Resources/values/strings.xml and every values-xx variant. If you rely on runtime ShortcutManagerCompat instead, MAUI's ResourceManager gives you the right string via AppResources.ResourceManager.GetString("ShortcutNewShort", CultureInfo.CurrentUICulture). See our localize .NET MAUI apps guide for the RESX plus culture switch story that composes with this.
How do you test app shortcuts?
On iOS the simulator supports 3D Touch and Haptic Touch: long-press an icon on the springboard and the menu appears. For CI, use xcrun simctl to launch with a synthetic shortcut key:
The list-shortcuts command is invaluable when static shortcuts don't appear at all. About 90% of the time, the XML has a parsing error and Android silently skipped it. You can also enable Show taps and long-press your own launcher to sanity-check both cold and warm activation. When you ship, add both flows to the smoke suite in the .NET MAUI testing guide's Appium section, because a single adb shell cmd shortcut invoke-shortcut before app launch catches routing regressions before they hit Play internal.
Frequently Asked Questions
How many app shortcuts can I have?
Both iOS and Android show up to four shortcuts in the long-press menu. Android's getMaxShortcutCountPerActivity() often returns five, but the stock Pixel launcher and most OEM launchers truncate at four, so plan for four.
What is the difference between static and dynamic shortcuts?
Static shortcuts are declared in a resource file (Info.plist on iOS, shortcuts.xml on Android) and ship with the app. Dynamic shortcuts are registered at runtime and can change based on user activity. Static ones always render first.
Do app shortcuts work in .NET MAUI on Windows or Mac Catalyst?
Windows exposes similar functionality through Jump Lists (JumpList.SaveAsync), and Mac Catalyst does not. The shortcut menu on macOS is limited to the Dock context menu, which uses a different API. Both are outside the scope of iOS and Android app shortcuts.
Why don't my Android shortcuts appear after install?
Usually one of three things: the <meta-data android:name="android.app.shortcuts"> tag is on the wrong activity, the XML fails to parse (check adb shell cmd shortcut list-shortcuts), or the launcher cache hasn't refreshed. Reinstall or bump the version code to force a refresh.
Do app shortcuts require any special permission?
No. Static and dynamic shortcuts work with no runtime permission on either platform. Pinned shortcuts on Android need only the user's confirmation in the system dialog, so no manifest permission is required.
Cross-platform engineering lead who's shipped apps to millions on both Play Store and App Store. Believes shared codebases shouldn't mean shared mediocrity.
Build custom haptic feedback in .NET MAUI 10 by calling iOS CoreHaptics and Android VibrationEffect directly. Full platform code, DI wiring, and the API pitfalls that break on iPad, low-power Android, and the iOS Simulator.
A working developer guide to CommunityToolkit MediaElement in .NET MAUI 10: install, XAML setup, HLS/DASH streaming, background audio, PiP, and fixes for the errors you will actually hit.
Add passkeys to .NET MAUI 10 using iOS AuthenticationServices and Android Credential Manager. Working C# handlers, association files, and a Fido2NetLib backend.
