Building a Cross-Platform QR Code Home Widget with Flutter

keeleyj
Jan 13
4 min read

Updated: Jan 22

Introduction

In today's mobile-first world, quick access to frequently used information is essential. Whether it's a vaccination card, membership ID, or digital business card, having instant access without opening an app can be a game-changer. That's why I built a Flutter application that puts your custom QR codes right on your home screen—available on both iOS and Android.

In this post (and the accompanying video tutorial), I'll walk you through how to create a cross-platform home screen widget that displays custom QR codes, and share the technical insights I gained along the way.

What Does It Do?

The application is beautifully simple:

1. Enter Your Data: Type in any text, URL, or data you want to encode as a QR code

2. Add a Label: Optionally customize the widget with a descriptive label

3. Generate & Preview: See a real-time preview of your QR code

4. Update Widget: Push the QR code to your device's home screen widget

5. Scan Anytime: Access your QR code instantly without opening the app

The widget adapts to different sizes on both platforms, ensuring your QR code looks great whether it's a small, medium, or large widget.

The Tech Stack

Core Technologies

• Flutter 3.9+: Cross-platform UI framework

• home_widget ^0.8.1: Bridge between Flutter and native widgets

• qr_flutter ^4.1.0: QR code generation library

• path_provider ^2.1.2: File system access for storing QR images

Platform-Specific Components

iOS (WidgetKit)

• SwiftUI for widget UI

• App Groups for data sharing

• Widget Extensions for home screen integration

Android

• Kotlin for widget provider

• SharedPreferences for data storage

• AppWidgetProvider for widget management

Key Technical Challenges

1. Cross-Platform Data Sharing

One of the biggest challenges was sharing data between the Flutter app and native widgets. iOS and Android handle this very differently:

iOS Solution: App Groups allow the main app and widget extension to share data through a common UserDefaults suite:

Android Solution: SharedPreferences with a specific name that both the app and widget can access:

2. High-Quality QR Code Generation

Simply generating a QR code wasn't enough—it needed to be scannable at various widget sizes. The solution involved:

1. High Resolution: Generating QR codes at 1024x1024 pixels

2. Error Correction: Using medium error correction level for better scanning

3. Image Conversion: Converting Flutter's QR painter output to PNG format

4. File Storage: Saving the image to a persistent location both platforms can access

Here's the core generation code:

3. Responsive Widget Layouts

The widget needed to look good across different sizes:

Android: Three separate layouts (small, medium, large) with dynamic selection based on widget dimensions:

iOS: SwiftUI's automatic scaling and responsive design:

User Experience Considerations

Note: This section is more of possible additions, things to add or consider. It's possible extras to add to your app or code.

Real-Time Preview

Before updating the widget, users see exactly what their QR code will look like. This immediate feedback prevents mistakes and builds confidence:

Loading States

Widget updates can take a moment, so clear loading indicators prevent user confusion:

All this gives users clear guidance on their home widget setup.

Full application code can be found here:

https://github.com/goshornjustin/home_screen_widget

Lessons Learned

1. Platform Differences Matter

Despite Flutter's "write once, run anywhere" promise, native widgets require platform-specific implementations. Embracing this rather than fighting it led to better results.

2. File Paths Are Tricky

Getting the correct file paths that both the Flutter app and native widgets could access required careful testing on both platforms. Using path_provider helped standardize this.

3. Widget Updates Aren't Instant

Unlike app UI updates, widget updates involve communication with the system. Setting proper user expectations through loading states is crucial.

4. Testing on Real Devices Is Essential

Widget behavior differs significantly between simulators and real devices, especially around file access and update timing.

Getting Started

Want to try it yourself? The project requires:

1. Flutter SDK 3.9+

2. iOS 18.0+ for iOS widgets

3. Android minSdk 21 for Android widgets

4. Xcode 16+ for iOS development

5. Android Studio for Android development

The key dependencies are minimal and well-maintained:

Conclusion

Building a cross-platform home screen widget taught me that Flutter's strength isn't just in creating beautiful UIs—it's in creating a unified development experience while still leveraging platform-specific features where they matter most.

The combination of Flutter's rapid development cycle with native widget capabilities creates something truly useful: instant access to your most important QR codes, all from a single codebase.

Whether you're building for personal use or creating a product, home screen widgets add tremendous value. And with Flutter, you can build them once and deploy everywhere.

Found this helpful? Consider:

• 💬 Leaving a comment with your questions

• 🔔 Subscribing for more Flutter tutorials

• ⭐ Starring the GitHub repository