AppActions.Icons.Maui

A .NET MAUI library that provides some default icons for AppActions without having to create your own.

adenearnshaw/AppActions.Icons.Maui: A .NET MAUI library that provides some default icons for AppActions without having to create your own. (github.com)

Features

Based on iOS' Home Screen Quick Action Icons, this library provides similar icons for both Android & Windows, but styled towards the platforms default design style. Also supports the use of SFSymbols as Icons on iOS.

Out-of-the-box icons available for Android, iOS & Windows
Use SF Symbols on iOS
Customise Android icons with brand colors
Builds on top of the Maui Essentials api
Specify different image names per platform

Getting Started

Add the AppActions.Icons.Maui nuget package to your MAUI project.
Setup you app actions as per the Maui Documentation

In your MauiProgram.CreateMauiApp(), add UseAppActionIcons() to your Essentials configuration builder.

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .ConfigureEssentials(essentials =>
        {
            essentials
                .UseAppActionIcons() // Add this line
                .AddAppAction("home_sc", "Home", icon: AppActionIcon.Home)
                .OnAppAction(App.HandleAppActions);
        });

    return builder.Build();
}

Now set the AppAction's icon property using one of the provided AppActionIcon options.

Using SF Symbols

Declare an SF Symbol for iOS and use your own custom icon on other platforms

Replace the icon property value with SystemSymbol() passing in the SF Symbol name.
```
.AddAppAction("record_sc", "Record", icon: new SystemSymbol("mic.circle.fill"))
```
On non-iOS platforms the periods (.) in the name are replaced with underscores (_). So mic.circle.fill will need a custom Android/Windows image called mic_circle_fill.
Add your icon for other platforms into the Resources\Images folder.

Using SF Symbols with AppActionIcon fallback

Declare an SF Symbol for iOS and use one of the other provided icons for other platforms

Use the PlatformString() to set specific icons for each platform within SystemSymbol
```
.AddAppAction("pause_sc", "Pause", icon: new SystemSymbol(new PlatformString(AppActionIcon.Prohibit, ios: "pause.circle.fill")))
```
This will use the default Pause icon on Window & Android. On iOS, this will use the SF Symbol of a filled circle with an pause icon in it.

Using a different icon per platform

The PlatformString can be used independently of SystemSymbol to be able to declare custom icons for each platform

Use the PlatformString() to set specific icons for each platform

.AddAppAction("stop_sc", "Stop", icon: new PlatformString("quicklaunch_stop", android: "ic_app_action_stop", ios: "quickaction_stop"))

Customise the icon colors on Android

Each Android icon uses a VectorDrawable and as such, the colors of the icon and the circle's background are variables that can be overriden.

In your app's Platforms\Android\Resources\values\colors.xml file, add additional properties for appActionBackground and appActionForeground.
```
<?xml version="1.0" encoding="utf-8"?>
<resources>
    ...

    <color name="appActionBackground">#E6DFFC</color>
    <color name="appActionForeground">#512BD4</color>
</resources>
```
When set the icons will change from the default gray color to those of your choosing.

Creating a custom icon

Each platform has different specifications for the icons needed for shortcuts.

Android

Android Icon Dimensions
Width	48px
Height	48px

Along with PNGs and JPGs, Android also supports VectorDrawables. A sample icon can be found here

iOS

iOS Icon Dimensions
Width	35px
Height	35px

Images should be added to the AssetCatalog with the Render As: option set to Template Image

Human Interface Guidelines - Quick Actions

Windows

Windows Icon Dimensions
Width	44px
Height	44px

Troubleshooting

Opening links in the same Android instance each time

If the app is backgrounded and a shortcut is tapped, your app may relaunch and re-initialized the App from scratch, wiping any existing navigation backstack. This is caused by the MainActivity recreating itself when coming in via the IntentFilter. To re-launch the app in the same instance that was backgrounded add the following property to the Activity attribute in your MainActivity

LaunchMode = LaunchMode.SingleTask