Quick guide on home screen quick actions for SwiftUI

Quick actions allow us to give users access to our app's functionality directly from the home screen, when they touch and hold the app icon.

For example, the native iOS Photos app offers quick actions to jump directly to recent photos, favorites, or search.

Let's look at how we can implement quick actions in our own apps.

Architecture & Design Patterns for iOS

This book is a practical guide to essential architectural principles and design patterns for iOS development. It covers strategies for building maintainable apps with Swift and SwiftUI, including dependency injection, navigation, common patterns, and modularization.

LEARN MORE

Adding quick actions

There are two ways to create quick actions:

1. Static quick actions – defined in the app's Info.plist, these are best for features that do not rely on app state.
2. Dynamic quick actions – created programmatically, these adapt to app state or user data.

Static quick actions

Static quick actions are straightforward to define. For instance, a "Favorites" action can be added by including the following configuration in the Info.plist:

<key>UIApplicationShortcutItems</key>
<array>
    <dict>
        <key>UIApplicationShortcutItemType</key>
        <string>favoritesAction</string>
        <key>UIApplicationShortcutItemIconSymbolName</key>
        <string>heart</string>
        <key>UIApplicationShortcutItemTitle</key>
        <string>Favorites</string>
    </dict>
</array>

Here’s what each key represents:

• UIApplicationShortcutItemType – A unique identifier for the action, used later when handling the action.
• UIApplicationShortcutItemIconSymbolName – Specifies an SF Symbol for the action’s icon.
• UIApplicationShortcutItemTitle – Displays the action’s title.

To add a subtitle, include the UIApplicationShortcutItemSubtitle key. Titles and subtitles can be localized using a InfoPlist.strings file:

<key>UIApplicationShortcutItemTitle</key>
<string>QUICK_ACTION_FAVORITES_TITLE</string>

With a matching key in the InfoPlist.strings:

"QUICK_ACTION_FAVORITES_TITLE" = "Favorites";

Dynamic quick actions

Dynamic quick actions are created programmatically and offer flexibility. For instance, we could add a "Favorites" action only if the user has saved favorites:

func updateShortcutItems() {
    guard !favorites.isEmpty else {
        UIApplication.shared.shortcutItems = []
        return
    }

    let favoritesAction = UIApplicationShortcutItem(
        type: "favoritesAction",
        localizedTitle: "Favorites",
        localizedSubtitle: nil,
        icon: UIApplicationShortcutIcon(systemImageName: "heart"),
        userInfo: [:])
    UIApplication.shared.shortcutItems = [favoritesAction]
}

This method can be called whenever the app enters the background to keep the quick actions up-to-date.

var body: some Scene {
    @Environment(\.scenePhase) private var scenePhase

    WindowGroup {
        ContentView()
    }
    .onChange(of: scenePhase) { (newScenePhase) in
        if newScenePhase == .background {
            updateShortcutItems()
        }
    }
}

Handling quick actions

Currently, SwiftUI does not offer a direct way to handle quick action events. Instead, we use UIKit's SceneDelegate to manage these interactions.

It provides the windowScene(_:performActionFor:completionHandler:) delegate method which is called when the app is currently in the background and a user selects a quick action.

If the app isn’t already loaded, it’s launched and the shortcut item is passed in through the connectionOptions parameter of the scene(_:willConnectTo:options:) delegate method.

class SceneDelegate: NSObject, UIWindowSceneDelegate {

    func windowScene(_ windowScene: UIWindowScene, performActionFor shortcutItem: UIApplicationShortcutItem, completionHandler: @escaping (Bool) -> Void) {
        handleShortcutItem(shortcutItem)
        completionHandler(true)
    }

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        if let shortcutItem = connectionOptions.shortcutItem {
            handleShortcutItem(shortcutItem)
        }
    }

    func handleShortcutItem(_ shortcutItem: UIApplicationShortcutItem) {
        if shortcutItem.type == "favoritesAction" {
            // Show favorites
        }
    }
}

In the handleShortcutItem method, we check the shortcut item's type property to determine which quick action was tapped.

To learn more about the SceneDelegate, check out the article on how to use the SceneDelegate in SwiftUI.

When debugging quick home screen actions from an app launch, we need a way to quit the app without loosing Xcode's debugger. Check out the article on how to debug iOS features that require app start from external actions to find out how to do that.