Capacitor App Shortcuts Plugin

Capacitor plugin to manage app shortcuts and quick actions.

Use Cases

The App Shortcuts plugin is typically used to give users faster access to key parts of your app right from the home screen icon, for example:

• Quick actions: Let users jump directly to frequently used screens such as search, compose, or feedback.
• Dynamic shortcuts: Create or update shortcuts at runtime based on user behavior, for example a shortcut to the most recently opened item.
• Default shortcuts: Define a set of default shortcuts in your Capacitor configuration without writing any code.
• Deep linking: React to shortcut clicks with the click listener and navigate the user to the corresponding screen.

Compatibility

Demo

A working example can be found here.

Android	iOS

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

 Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-app-shortcuts` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands:

npm install @capawesome/capacitor-app-shortcuts
npx cap sync

Configuration

Examples

In capacitor.config.json:

{
  "plugins": {
    "AppShortcuts": {
      "shortcuts": [{ id: 'feedback', title: 'Feedback' }]
    }
  }
}

In capacitor.config.ts:

/// <reference types="@capawesome/capacitor-app-shortcuts" />

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    AppShortcuts: {
      shortcuts: [{ id: 'feedback', title: 'Feedback' }],
    },
  },
};

export default config;

iOS

If your app uses the UIScene lifecycle (default since Capacitor 8.5), add the following to your app's SceneDelegate.swift:

+ import AppShortcutsPlugin

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        guard let windowScene = scene as? UIWindowScene else { return }

        window = UIWindow(windowScene: windowScene)
        window?.rootViewController = CAPBridgeViewController()
        window?.makeKeyAndVisible()

+        if let shortcutItem = connectionOptions.shortcutItem {
+            NotificationCenter.default.post(name: NSNotification.Name(AppShortcutsPlugin.notificationName), object: nil, userInfo: [AppShortcutsPlugin.userInfoShortcutItemKey: shortcutItem])
+        }

        SceneDelegateProxy.shared.scene(scene, willConnectTo: session, options: connectionOptions)
    }

+    func windowScene(_ windowScene: UIWindowScene, performActionFor shortcutItem: UIApplicationShortcutItem, completionHandler: @escaping (Bool) -> Void) {
+        NotificationCenter.default.post(name: NSNotification.Name(AppShortcutsPlugin.notificationName), object: nil, userInfo: [AppShortcutsPlugin.userInfoShortcutItemKey: shortcutItem])
+        completionHandler(true)
+    }

If your app does not use the UIScene lifecycle, add the following to your app's AppDelegate.swift instead:

+ import AppShortcutsPlugin

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+        if let shortcutItem = launchOptions?[.shortcutItem] as? UIApplicationShortcutItem {
+            NotificationCenter.default.post(name: NSNotification.Name(AppShortcutsPlugin.notificationName), object: nil, userInfo: [AppShortcutsPlugin.userInfoShortcutItemKey: shortcutItem])
+            return false
+        }
        return true
    }

+    func application(_ application: UIApplication, performActionFor shortcutItem: UIApplicationShortcutItem, completionHandler: @escaping (Bool) -> Void) {
+        NotificationCenter.default.post(name: NSNotification.Name(AppShortcutsPlugin.notificationName), object: nil, userInfo: [AppShortcutsPlugin.userInfoShortcutItemKey: shortcutItem])
+        completionHandler(true)
+    }

If your project still uses CocoaPods instead of Swift Package Manager (SPM), import CapawesomeCapacitorAppShortcuts rather than AppShortcutsPlugin:

+ import CapawesomeCapacitorAppShortcuts

Usage

The following examples show how to create, get, and remove app shortcuts and listen for shortcut clicks.

Create or update app shortcuts

Use the set(...) method to create or update the app shortcuts. Each shortcut needs a unique identifier and a title. Only available on Android and iOS:

import { AppShortcuts } from '@capawesome/capacitor-app-shortcuts';

const set = async () => {
  await AppShortcuts.set({
    shortcuts: [
      {
        id: 'feedback',
        title: 'Feedback',
        description: 'Send us your feedback',
      },
      {
        id: 'rate',
        title: 'Rate',
        description: 'Rate our app',
      }
    ],
  });
};

Get all app shortcuts

Retrieve the list of app shortcuts that are currently set. Only available on Android and iOS:

import { AppShortcuts } from '@capawesome/capacitor-app-shortcuts';

const get = async () => {
  const result = await AppShortcuts.get();
  return result.shortcuts;
};

Remove all app shortcuts

Clear all app shortcuts, for example when the user signs out. Only available on Android and iOS:

import { AppShortcuts } from '@capawesome/capacitor-app-shortcuts';

const clear = async () => {
  await AppShortcuts.clear();
};

Listen for shortcut clicks

Add a listener for the click event to react when the user taps an app shortcut, for example to navigate to the corresponding screen. On iOS, this requires the changes to your AppDelegate.swift described in the iOS configuration instructions:

import { AppShortcuts } from '@capawesome/capacitor-app-shortcuts';

const addListener = async () => {
  AppShortcuts.addListener('click', (event) => {
    console.log('Shortcut clicked:', event.shortcutId);
  });
};

API

• clear()
• get()
• set(...)
• addListener('click', ...)
• removeAllListeners()
• Interfaces

clear()

clear() => Promise<void>

Remove all app shortcuts.

Only available on Android and iOS.

Since: 6.0.0

get()

get() => Promise<GetResult>

Get all app shortcuts.

Only available on Android and iOS.

Returns: Promise<GetResult>

Since: 6.0.0

set(...)

set(options: SetOptions) => Promise<void>

Create or update app shortcuts.

Only available on Android and iOS.

Since: 6.0.0

addListener('click', ...)

addListener(eventName: 'click', listenerFunc: (event: ClickEvent) => void) => Promise<PluginListenerHandle>

Called when an app shortcut is clicked.

Only available on Android and iOS.

Returns: Promise<PluginListenerHandle>

Since: 6.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 6.0.0

Interfaces

GetResult

Shortcut

SetOptions

PluginListenerHandle

ClickEvent

FAQ

Which platforms are supported by this plugin?

App shortcuts are a native concept of the Android launcher and the iOS home screen, so the plugin is only available on Android and iOS. All plugin methods and the click event are marked as only available on Android and iOS in the API section.

Why is the click listener not called on iOS?

On iOS, the plugin relies on changes to your app's AppDelegate.swift to forward shortcut items to the plugin. Make sure you have applied the code changes described in the iOS configuration instructions. Without them, the click event is never delivered.

Can I define app shortcuts without writing any code?

Yes, you can use the shortcuts configuration option to define a list of app shortcuts that are set by default. See the Configuration section for examples in capacitor.config.json and capacitor.config.ts.

Can I use different icons on Android and iOS?

Yes, you can use the androidIcon and iosIcon properties to provide platform-specific icons, or the icon property for both platforms. On Android, drawable resources and base64 encoded images are supported, while on iOS you can use system symbol names, asset catalogue images, or UIApplicationShortcutIcon types. Note that on iOS, the icon and the description must be used together.

Can I use this plugin with Ionic, React, Vue or Angular?

Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects.

Related Plugins

• App Icon: Change the app icon at runtime.
• Badge: Access and update the badge number of the app icon.

Newsletter

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

License

See LICENSE.