Code Reference

React Native Launcher Shortcuts

React Native · Quick Reference

React Native Launcher Shortcuts

React Native · Quick Reference


📋 Overview

Android App Shortcuts allow users to long-press your app icon to access quick actions directly from the launcher. Supported on Android 7.1+ (API 25+).


🔧 Core Concepts

Shortcut TypeDescription
StaticDefined in AndroidManifest.xml, fixed at build time
DynamicAdded/removed at runtime via JavaScript
PinnedUser manually pins to home screen (cannot be removed programmatically)

🚀 Libraries

npm install @rn-org/react-native-shortcuts
# or
yarn add @rn-org/react-native-shortcuts

Alternative: @mobigaurav/react-native-quick-actions

npm install @mobigaurav/react-native-quick-actions

💡 Basic Implementation

Check Support & Add Shortcuts

import Shortcuts from '@rn-org/react-native-shortcuts'

// Check if supported (Android 7.1+)
const supported = await Shortcuts.isShortcutSupported()

// Add shortcuts
await Shortcuts.addShortcut({
  id: 'compose',
  title: 'Compose',
  longLabel: 'Start new message', // Max 25 chars
  iconName: 'ic_compose'          // Drawable resource name
})

await Shortcuts.addShortcut({
  id: 'search', 
  title: 'Search',
  iconName: 'ic_search'
})

// Remove all shortcuts
await Shortcuts.removeAllShortcuts()

// Remove specific shortcut
await Shortcuts.removeShortcut('compose')

Handle Shortcut Navigation

import { useEffect, useRef } from 'react'
import Shortcuts from '@rn-org/react-native-shortcuts'

function App() {
  // Handle initial launch via shortcut (cold start)
  useEffect(() => {
    const checkInitial = async () => {
      const id = await Shortcuts.getInitialShortcutId()
      if (id) navigateToShortcut(id)
    }
    checkInitial()
  }, [])

  // Handle shortcut when app is in background (warm start)
  useEffect(() => {
    const sub = Shortcuts.addOnShortcutUsedListener((id) => {
      navigateToShortcut(id)
    })
    return () => sub.remove()
  }, [])

  const navigateToShortcut = (id: string) => {
    switch(id) {
      case 'compose': navigation.navigate('Compose'); break
      case 'search': navigation.navigate('Search'); break
    }
  }

  return <YourApp />
}

🎨 Android Icons

Add icons to android/app/src/main/res/drawable/:

android/app/src/main/res/drawable/
  ├── ic_compose.xml      # Vector drawable
  ├── ic_search.png       # PNG image
  └── ic_settings.xml

Requirements:

  • Material Design guidelines
  • Vector (XML) preferred over raster (PNG)
  • 48dp x 48dp recommended

📋 Android Manifest Setup

For static shortcuts (optional - pre-defined at build time):

<!-- android/app/src/main/AndroidManifest.xml -->
<application ...>
  <activity android:name=".MainActivity">
    <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>

    <!-- Static shortcuts -->
    <meta-data
      android:name="android.app.shortcuts"
      android:resource="@xml/shortcuts" />
  </activity>
</application>
<!-- android/app/src/main/res/xml/shortcuts.xml -->
<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <shortcut
    android:shortcutId="compose"
    android:enabled="true"
    android:icon="@drawable/ic_compose"
    android:shortcutShortLabel="Compose"
    android:shortcutLongLabel="Compose Message">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="com.yourapp"
      android:targetClass="com.yourapp.MainActivity" />
    <categories android:name="android.shortcut.conversation" />
  </shortcut>
</shortcuts>

⚠️ Pitfalls

IssueSolution
Pinned shortcuts cannot be removed programmaticallyUser must unpin manually
4 shortcut limit (dynamic + static)Prioritize most used actions
Launch mode issuesCheck android:launchMode in manifest
Icon not showingVerify drawable resource exists and is correctly named


📚 Documentation

On this page