Skip to content

@capawesome/capacitor-app-shortcuts

Capacitor plugin to manage app shortcuts and quick actions.

Deliver Live Updates to your Capacitor app with Capawesome Cloud

Newsletter

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

Compatibility

Plugin Version Capacitor Version Status
8.x.x >=8.x.x Active support

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

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

Prop Type Description Since
shortcuts Shortcut[] The list of app shortcuts that should be set by default. Only available on Android and iOS. 7.2.0

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

On iOS, you must add the following to your app's AppDelegate.swift:

+ import CapawesomeCapacitorAppShortcuts

@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 true
+        }
        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)
+    }

Demo

A working example can be found here.

Android iOS

Usage

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

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

const get = async () => {
  const result = await AppShortcuts.get();
  return result.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',
      }
    ],
  });
};

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

API

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.

Param Type
options SetOptions

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.

Param Type
eventName 'click'
listenerFunc (event: ClickEvent) => void

Returns: Promise<PluginListenerHandle>

Since: 6.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 6.0.0

Interfaces

GetResult

Prop Type Description Since
shortcuts Shortcut[] The list of app shortcuts. 6.0.0

Shortcut

Prop Type Description Since
description string The description. On Android, the launcher shows this instead of the short title when it has enough space. Attention: On iOS, the icon and the description must be used together. 6.0.0
id string The unique identifier. 6.0.0
title string The display name. 6.0.0
icon string | number The icon to display. On Android, the icon can be one of the following: - An integer value of the R.drawable enum (e.g. 17301547). - A string that represents the name of the drawable resource (e.g. "alert_dark_frame"). - A base64 encoded image string (e.g. "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAASABIAAD/4QC..."). On iOS, the icon can be one of the following: - The constant integer value of the UIApplicationShortcutIcon.IconType enum (e.g. 6). - A system symbol name (e.g. star.fill). - Name of the image asset from the asset catalogue. 6.1.0
androidIcon string | number The icon to display on Android. The icon can be one of the following: - An integer value of the R.drawable enum (e.g. 17301547). - A string that represents the name of the drawable resource (e.g. "alert_dark_frame"). - A base64 encoded image string (e.g. "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAASABIAAD/4QC..."). 7.2.0
iosIcon string | number The icon to display on iOS. The icon can be one of the following: - The constant integer value of the UIApplicationShortcutIcon.IconType enum (e.g. 6). - A system symbol name (e.g. star.fill). - Name of the image asset from the asset catalogue. 7.2.0

SetOptions

Prop Type Description Since
shortcuts Shortcut[] The list of app shortcuts. 6.0.0

PluginListenerHandle

Prop Type
remove () => Promise<void>

ClickEvent

Prop Type Description Since
shortcutId string The unique identifier of the app shortcut that was clicked. 6.0.0

Changelog

See CHANGELOG.md.

License

See LICENSE.