Flutter Pinned Shortcuts 📌

✨ A Flutter plugin that lets you create Android pinned shortcuts with style! Pin your app's most important features directly to the user's home screen.

pinned-shortcuts

✅ Features

📱 Create pinned shortcuts on Android home screens
🖼️ Support for various image sources:
- 📦 Flutter assets
- 🤖 Android resources
- 🌐 Network images (auto-downloaded)
- 📂 File paths
- 🔀 Support for adaptive icons
👂 Listen to shortcut clicks in Flutter
🔍 Check if a shortcut is pinned

🚀 Getting Started

📥 Installation

Add this to your package's pubspec.yaml file:

dependencies:
  pinned_shortcuts: any

Then run:

$ flutter pub get

📱 Android Setup

Ensure your minSdkVersion is at least 16 (Android 4.1) in your app's android/app/build.gradle file:

android {
    defaultConfig {
        minSdkVersion 16
        // ...
    }
}

For optimal functionality, Android 8.0 (API level 26) or higher is recommended.

💻 Usage

🚀 Initialize the plugin

First, initialize the plugin (typically in your main.dart):

import 'package:pinned_shortcuts/pinned_shortcuts.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize the plugin
  await FlutterPinnedShortcuts.initialize();
  
  runApp(MyApp());
}

✅ Check if pinned shortcuts are supported

bool isSupported = await FlutterPinnedShortcuts.isSupported();
if (isSupported) {
  print('🎉 Pinned shortcuts are supported!');
} else {
  print('😔 Pinned shortcuts are not supported on this device');
}

📌 Create a pinned shortcut

With a Flutter asset image

await FlutterPinnedShortcuts.createPinnedShortcut(
  id: 'asset_shortcut',
  label: 'My Shortcut',
  imageSource: 'assets/icon.png',
  imageSourceType: ImageSourceType.asset,
  longLabel: 'My Flutter Asset Shortcut', // Optional
  extraData: {'source': 'asset'}, // Optional data to pass when shortcut is clicked
);

With an Android resource image

await FlutterPinnedShortcuts.createPinnedShortcut(
  id: 'resource_shortcut',
  label: 'Resource Shortcut',
  imageSource: 'ic_launcher', // drawable asset name
  imageSourceType: ImageSourceType.resource,
);

With a network image

await FlutterPinnedShortcuts.createPinnedShortcut(
  id: 'network_shortcut',
  label: 'Network Shortcut',
  imageSource: 'https://example.com/image.png',
  imageSourceType: ImageSourceType.network,
);

With a file path

await FlutterPinnedShortcuts.createPinnedShortcut(
  id: 'file_shortcut',
  label: 'File Shortcut',
  imageSource: '/path/to/file.png',
  imageSourceType: ImageSourceType.file,
);

With Adaptive icon with background color

await FlutterPinnedShortcuts.createPinnedShortcut(
  id: 'file_shortcut',
  label: 'File Shortcut',
  imageSource: 'https://example.com/image.png', // Legacy fallback
  imageSourceType: ImageSourceType.network,
  adaptiveIconForeground: 'https://example.com/image.png',
  adaptiveIconBackground: '#2196F3', // Material Blue
  adaptiveIconBackgroundType: AdaptiveIconBackgroundType.color,
  extraData: {'type': 'adaptive_color'},
);

With Adaptive icon with background image

await FlutterPinnedShortcuts.createPinnedShortcut(
  id: 'file_shortcut',
  label: 'File Shortcut',
  imageSource: 'assets/icon.png', // Legacy fallback
  imageSourceType: ImageSourceType.asset,
  adaptiveIconForeground: 'assets/icon_foreground.png',
  adaptiveIconBackground: 'assets/icon_background.png',
  adaptiveIconBackgroundType: AdaptiveIconBackgroundType.image,
  extraData: {'type': 'adaptive_color'},
);

👂 Listen to shortcut clicks

Set up a listener for when shortcuts are clicked:

FlutterPinnedShortcuts.onShortcutClick.listen((Map resultData) {
  debugPrint('🎉 Shortcut clicked: id : ${resultData['id']}, extraData: ${resultData['extraData']}');
  // Handle the shortcut click, e.g., navigate to a specific screen
});

🔍 Check if a shortcut is pinned

bool isPinned = await FlutterPinnedShortcuts.isPinned('shortcut_id');
if (isPinned) {
  print('📌 Shortcut is pinned!');
} else {
  print('🚫 Shortcut is not pinned');
}

♻️ Dispose the plugin

// Call this when you're done with the plugin, typically in the dispose method
@override
void dispose() {
  FlutterPinnedShortcuts.dispose();
  super.dispose();
}

📚 API Reference