Logo for tanaschita.com

Quick guide on home screen quick actions for iOS

Learn how to give users access to your app's functionality directly from the home screen.

18 Apr 2022 · 4 min read

Starting with iOS 13, we can use quick actions to give users access to our app's functionality directly from the home screen, when they touch and hold the app icon.

Quick actions of the native iOS Photos app.
Quick actions of the native iOS Photos app.

The native iOS Photos app for example provides quick actions to directly jump to the most recent photos, to favorites or to search.

Let's look at how we can add quick actions to our own apps.

Adding quick actions

There are two ways to implement quick actions:

  1. As static quick actions by using the project's Info.plist - for actions which don't depend on any app state.
  2. As dynamic quick actions in code - for actions that depend on specific app state or data.

Static quick actions

Here is how a favorites action might be defined 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 is what's happening in the definitions above:

We could also setup a subtitle with UIApplicationShortcutItemSubtitle. To localize the title or subtitle, we use a localized 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 provide us more flexibility, for example we could add the favorites action depending on whether the user has any favorites.

func updateShortcutItems() {
guard !favorites.isEmpty else {
UIApplication.shared.shortcutItems = []
return
}
let favoritesAction = UIApplicationShortcutItem(
type: "favoritesAction",
localizedTitle: "favoritesAction.title",
localizedSubtitle: nil,
icon: UIApplicationShortcutIcon(systemImageName: "heart"),
userInfo: [:])
UIApplication.shared.shortcutItems = [favoritesAction]
}

We could call this method every time the iOS app goes into background to always keep the 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

SwiftUI doesn’t provide a mechanism to respond to events from quick actions yet. For the time being, we can use UIKit's SceneDelegate to handle them.

It provides the windowScene(_:performActionFor:completionHandler:) delegate method which is called when the app is currently in the background and the 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.

And that's basically it.

If the mixing of SwiftUI, UIKit and their lifecycle events above was a little confusing for you, check out the article on Understanding the difference between AppDelegate, SceneDelegate and SwiftUI's App protocol to learn more about how those types are connected.

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 quitting and restarting the application to find out how to do that.

Image of books
Further reading: Swift Power Pack
For further reading, check out the Swift Power Pack books by Paul Hudson. The bundle delivers six books from beginner to advanced around Swift topics.

Newsletter

Receive a monthly newsletter about the latest articles and tips.

Image of a reading marmot

Related tags

Written by

Articles with related topics

Latest articles and tips