Disclaimer: This Article was fully written by hand. AI was used only for grammar and typo correction

Recently I announced a new way to use the home_widget ecosystem to write Homescreen Widgets for Flutter Apps fully in Dart without needing to touch native code.

With some recent additions it is now possible to write a Duolingo-style Streak Widget fully in Dart. This has always been something I wanted to do because trying out Duolingo’s Widgets is what actually got me started using Duolingo (current streak is 1058 for those wondering)

The characteristics of a Duolingo-style widget

The key features for a Duolingo-style Widget are:

• Show current streak and if completed for today or not
• Background Image getting more and more unhinged throughout the day
• All of that using a Bird Mascot

Especially the Bird fact makes it the perfect case to build Dasholingo. It’s Flutter after all!

The home_widget features making this work

Most features were already possible in the new home_widget way of writing widgets but what was missing was always having automatic updates based on time.

This can be useful to swap out a picture of a bird getting angrier throughout the day, but is also really handy if you want to display any kind of timed data throughout the day like calendar events or weather forecasts.

On iOS this was quite straightforward as iOS Homescreen Widgets operate using a Timeline. You define data points and iOS will update the widget automatically.

For Android no such concept exists out of the box. However as home_widget_generator is based on code generation home_widget will now generate the needed infrastructure automatically to update the widget with the needed data automatically using automatically scheduled alarms.

In Practice

To get these timed updates working in home_widget there are two parts to it. Defining it in the widget and using it in the generated helper to send data.

Defining the Widget

When you want to use timed data in a Widget it is as simple as wrapping your data field with a HWTimedData.

import 'package:home_widget_generator/home_widget_generator.dart';

@HomeWidget(
  name: 'Streak',
  android: HomeWidgetAndroidConfiguration(),
  iOS: HomeWidgetIOSConfiguration(
    groupId: 'group.com.example.app',
    supportedFamilies: [HWWidgetFamily.systemSmall],
  ),
  widget: HWStack(
    fit: HWStackFit.expand,
    children: [
      // Timed Data to update the Background Image
      HWImage(
        HWTimedData(HWImageData('mascot')),
        fit: HWImageFit.cover,
      ),
      HWAlign(
        alignment: HWAlignment.topStart,
        child: HWText(
          // Non timed Data value for the streak
          HWInt('streak', defaultValue: 0),
          style: HWTextStyle(fontSize: 28, fontWeight: HWFontWeight.bold),
        ),
      ),
      HWAlign(
        alignment: HWAlignment.bottomCenter,
        child: HWText(
          // Timed Data for an optional Message
          HWTimedData(HWString('message', defaultValue: 'Open the app')),
        ),
      ),
    ],
  ),
)
class Streak {}

Sending timed data

The widget helper that gets generated will then contain a field for timed data which you pass in a Map<DateTime, WidgetData> where WidgetData is a generated object containing all fields you defined as being time dependent.

In our streak example this looks like this:

await StreakHomeWidget.saveData(
  streak: 82,
  timedData: {
    now: StreakTimedData(
      mascot: AssetImage('assets/dash/time_wait.png'),
      message: 'Dash is waiting',
    ),
    // …more slots
  },
);

More Info

Check out the full example in the GitHub Repo of home_widget

If you like my work on home_widget and it is helpful for your project please consider sponsoring:

Sponsor @ABausG on GitHub Sponsors

Reach out to me if you have more questions:

• Anton Borries (@ABausG) on X
• Anton Borries - 1KOMMA5° | LinkedIn
• Anton (@abausg.bsky.social)

1. Setting up a new Widget requires native additions and clicking around in the Xcode UI
2. You have to write Widget Code natively and crucially twice

I am very excited to announce some new additions to the home_widget ecosystem solving both of these issues.

home_widget_cli

I created a new cli package home_widget_cli that helps in adding all the necessary boilerplate for setting up widgets for both Android and iOS. No opening of Android Studio or Xcode required.

Install the cli

dart pub global activate home_widget_cli

Create a widget

home_widget create WeatherForecastWidget

This will then wire up all the necessary code for you to start building out the UI. Sending data and updating widgets still works the same way using the home_widget package.

home_widget_generator

The cli also provides a generate command which combines with a new home_widget_generator to allow writing Homescreen Widgets fully in Dart.

1. UI Code on the native side for both iOS and Android
2. Simple Dart helper classes to update the Widgets

Basic Example

Add home_widget_generator as a dependency in pubspec.yaml

dev_dependencies:
  home_widget_generator: ^0.0.1
  # You can also add the cli as a dev dependency to do dart run home_widget generate
  home_widget_cli: ^0.0.1

Create a basic Widget Definition next to your your lib folder

my_project/
  home_widget/
    greeting_widget.dart <-- Add the file here
  lib/  
  test/ 

import 'package:home_widget_generator/home_widget_generator.dart';

@HomeWidget(
  name: 'Greeting',
  android: HomeWidgetAndroidConfiguration(),
  iOS: HomeWidgetIOSConfiguration(
    groupId: 'group.es.antonborri.generatorBasics',
    supportedFamilies: [HWWidgetFamily.systemSmall],
  ),
  widget: HWColumn(
    crossAxisAlignment: HWCrossAxisAlignment.start,
    children: [
      HWText.fixed(
        'Hello',
        style: HWRoleTextStyle(role: HWTextStyleRole.caption),
      ),
      HWText(
        HWString('name', defaultValue: 'world'),
        style: HWRoleTextStyle(
          role: HWTextStyleRole.title,
          fontWeight: HWFontWeight.bold,
        ),
      ),
    ],
  ),
)
class Greeting {}

Running home_widget generate (or dart run home_widget generate it you added the cli dependency) this will produce native Homescreen Widgets on both iOS and Android

To update you simply need to call the generated helpers

await GreetingHomeWidget.saveData(name: 'Anton');
await GreetingHomeWidget.updateWidget();

Conditionally showing and Formatting

home_widget_generator also allows generating Widgets that rely on specific data being set or which values they have. For example you can check if a value is stored and if it is true/false

import 'package:home_widget_generator/home_widget_generator.dart';

@HomeWidget(
  name: 'Conditional Status',
  android: HomeWidgetAndroidConfiguration(),
  iOS: HomeWidgetIOSConfiguration(
    groupId: 'group.es.antonborri.generatorBasics',
    supportedFamilies: [HWWidgetFamily.systemSmall],
  ),
  widget: HWFill(
    child: HWDataExists(
      data: HWBool('hasData'),
      whenPresent: HWBoolConditional(
        data: HWBool('enabled', defaultValue: true),
        whenTrue: HWColumn(
          mainAxisAlignment: HWMainAxisAlignment.center,
          crossAxisAlignment: HWCrossAxisAlignment.center,
          children: [
            HWText.fixed(
              'Enabled',
              style: HWRoleTextStyle.headline(
                color: HWColor.fixed(0xFF16A34A),
              ),
            ),
          ],
        ),
        whenFalse: HWColumn(
          mainAxisAlignment: HWMainAxisAlignment.center,
          crossAxisAlignment: HWCrossAxisAlignment.center,
          children: [
            HWText.fixed(
              'Disabled',
              style: HWRoleTextStyle.headline(
                color: HWColor.fixed(0xFFDC2626),
              ),
            ),
          ],
        ),
      ),
      whenAbsent: HWColumn(
        mainAxisAlignment: HWMainAxisAlignment.center,
        crossAxisAlignment: HWCrossAxisAlignment.center,
        children: [
          HWText.fixed('No Data', style: HWRoleTextStyle.headline()),
          HWText.fixed(
            'Open the app',
            style: HWRoleTextStyle(
              role: HWTextStyleRole.caption,
              color: HWDefaultColor(HWColorRole.contentSecondary),
            ),
          ),
        ],
      ),
    ),
  ),
)
class ConditionalStatus {}

These are the first Preview releases of the Packages. More Info and Features are coming soon. Please try them out, read the documentation and leave feedback via GitHub

Please consider supporting the future work of home_widget through GitHub Sponsors

Sponsor @ABausG on GitHub Sponsors

If you have any questions feel free to reach out via social media as well:

Bluesky
Twitter
LinkedIn

A while back I wrote about how to build Configurable Home Screen Widget for Flutter Apps on iOS.

Configurable Home Screen Widget for Flutter Apps on iOS

I’m super happy to announce that, thanks to mainly a community contribution, home_widget now supports this also for Android Apps.

This Article will cover the necessary steps in order to make a Widget configurable.

The concept

Homescreen widgets on Android use a dedicated Configuration Activity to launch the app indicating that a user wants to configure a specific Widget.

You can detect when your App was launched this way using a new callback in Flutter. However I would recommend to configure it to launch in a dedicated Flutter entrypoint meaning you don’t have to launch the Full App just for these configuration changes as well as worry less about life cycle issues.

This Guide assumes you already have created the basic Widget Scaffold e.g following this guide

Ensure you use at least home_widget 0.9.1

// pubspec.yaml

dependencies:
  ...
  home_widget: ^0.9.1

Android Setup

On Android we need to do three steps in order to tell the OS that a specific Widget is configurable.

1. Create a Configuration Activity
2. Tell the Widget to use this Activity for Configuration
3. Ensure the AndroidManifest knows that this Activity can be used for configuration

Create a Configuration Activity

Next to your MainActivity.kt create a new dedicated Activity for the Configuration

package com.example.app

import io.flutter.embedding.android.FlutterActivity

class WidgetConfigurationActivity : FlutterActivity() {
  override fun getDartEntrypointFunctionName(): String = "configureMain"
}

We will create a new Dart Entry Point with configureMain later.

Tell the Widget to use this Activity for Configuration

In the widget’s configuration xml make the widget configurable and point it to the newly created activity

<appwidget-provider
  xmlns:android="http://schemas.android.com/apk/res/android"
  ...
  android:widgetFeatures="reconfigurable"
  android:configure="com.example.app.WidgetConfigurationActivity" />

Adjust AndroidManifest

Add the new Activity to the AndroidManifest.xml similar to how the Main Activity is present

<activity
    android:name=".WidgetConfigurationActivity"
    android:exported="true"
    android:launchMode="singleTop"
    ... >
    <meta-data
        android:name="io.flutter.embedding.android.NormalTheme"
        android:resource="@style/NormalTheme" />
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE" />
    </intent-filter>
</activity>

Ensure you add the <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE" /> intent filter to the activity so the System knows how to launch this activity.

Now when the User adds the Widget to the Homescreen they will be prompted to configure it

Flutter Setup

As already hinted above we will create a dedicated dart entry point that will be called whenever the user wants to configure the Homescreen Widget. We need to do the following steps

1. Create dedicated Entrypoint to launch the configuration ui
2. Present the configuration UI
3. Finish the configuration

Create Entrypoint

In your main.dart file add a new global method next to the existing main()

  @pragma('vm:entry-point')
  Future<void> configureMain() async {
    WidgetsFlutterBinding.ensureInitialized();
    // Validate that the App was indeed launched for configuration
    // If this is non-null it is the id of the widget the user wants to configure
    final configuredWidgetId =
        await HomeWidget.initiallyLaunchedFromHomeWidgetConfigure();

    if (configuredWidgetId != null) {
      // Call runApp with whatever UI you want to present for configuration
      return runApp(MaterialApp(
        home: YourConfigurationScreen(widgetId: configuredWidgetId),
      ));
    }
    // As a fallback launch the usual main app
    return main();
  }

Present the configuration UI

HomeWidget.initiallyLaunchedFromHomeWidgetConfigure() will return a non null widgetId for the widget that should be configured. Use this Widget id to store configured values specifically for this widget.

e.g in the UI you may have a dropdown field so select a specific value. Use the widgetId when you save it using something like HomeWidget.saveWidgetData('name.$widgetId', 'World')

ListTile(
  title: const Text('Name'),
  trailing: DropdownButton(
    value: name,
    onChanged: (value) {
      saveName(value);
    },
    items: ['World', 'Universe', 'Flutter Community']
        .map((option) => DropdownMenuItem(
              value: option,
              child: Text(option),
            ))
        .toList(),
  ),
); 

...

Future<void> saveName(String? name) async {
  // Use the widgetId returned from HomeWidget.initiallyLaunchedFromHomeWidgetConfigure()
  await HomeWidget.saveWidgetData('name.$widgetId', name);
}

Finish the configuration

Once the user has finished making the configurations and you have saved all the values to Home Widget, update the widget and then crucially call HomeWidget.finishHomeWidgetConfigure() to finish the configuration. Without this Android will not properly mark the widget as configured.

Ideally instead of saving the configuration on each edit store it in a local state and only save the data and update the widget once the user makes a “Save” Action

Future<void> _saveConfiguration() async {
  await HomeWidget.saveWidgetData('name.$widgetId', name);
  await HomeWidget.saveWidgetData('punctuation.$widgetId', punctuation);
  await HomeWidget.updateWidget(name: 'MyWidget');
  // Don't forget to call this
  await HomeWidget.finishHomeWidgetConfigure();
}

Closing the loop

Back on the Android side, when building the Compose UI, use the key with the `widgetId` to get the user configured value when showing the widget:

class ConfigurableWidgetHomeWidget : GlanceAppWidget() {
  override val stateDefinition = HomeWidgetGlanceStateDefinition()

  override suspend fun provideGlance(context: Context, id: GlanceId) {
    val appWidgetId = GlanceAppWidgetManager(context).getAppWidgetId(id)
    provideContent { WidgetContent(appWidgetId, currentState()) }
  }

  @Composable
  private fun WidgetContent(appWidgetId: Int, currentState: HomeWidgetGlanceState) {
    val prefs = currentState.preferences
    val nameKey = "name.$appWidgetId"
    val name = prefs.getString(nameKey, "World")

    Column() {
      Text(text = "Hello")
      if (!name.isNullOrEmpty()) {
        Text(text = name)
      }
    }
  }
}

Full Example

For a full example check out the android/ implementation of the Configurable Widget Example in the home_widget repository

home_widget/examples/configurable_widget at main · ABausG/home_widget

Other new Features of home_widget

home_widget now supports saving files and images directly. This makes it a lot easier to e.g pass API Responses as data for widgets or using bundled assets or network Images to present them on native widgets.

await HomeWidget.saveFile('key', someBytesAsUint8List);

await HomeWidget.saveImage('key', imageProvider);

This will store the path to the file for key similar to how renderFlutterWidget did it.

You can find an example of this on Github

Thanks for reading. If you like home_widget and want to support future development consider sponsoring on Github

Sponsor @ABausG on GitHub Sponsors

If you have any questions reach out to me on social media:

Anton (@abausg.bsky.social)

https://www.linkedin.com/in/abausg/

JavaScript is not available.

In this Article I will go through the necessary setup steps, how to share data and how to display data from your Flutter App in an Apple Watch App.

Adding an Apple Watch App

In order to get started with adding a watch App open Xcode and go : File > New > Target > watchOS > App and fill out the metadata ensuring you select Watch App for Existing iOS App and selecting your Flutter Runner App

WatchConnectivity

When you now run your App on an iPhone you can see your App available for installation in the Watch App on your phone. However simply having the companion app is not really what we want. We want to share data between the apps on the phone and the watch.

Ever since watchOS 2 (which was released in 2015) you need to use WatchConnectivity. While the API has changed in some ways, the basic concept is still centered around having a WCSession and a WCSessionDelegate. How it works is to connect a SessionDelegate to a session from both the phone app as well as the watch app.

Of course you could wrap the native APIs yourself to make sure your Flutter app can connect to the session. However you can also use the great Flutter Community and use packages from pub.dev where someone may already have wrapped it. In the case of Watch Connectivity there are actually multiple plugins already for this. For the remainder of this article I will be using the package flutter_watch_os_connectivity

Connecting to the Session from Flutter

Using the plugin it is actually super easy to connect and activate the session.

final watchConnectivity = FlutterWatchOsConnectivity();
await watchConnectivity.configureAndActivateSession()

That’s it. Your flutter app is connected to a WatchSession. The plugin also offers callbacks like getActivateState for checking the session state, getPairedDeviceInfo for checking if a watch is currently paired and getReachability to check if the watch app is currently paired/reachable. All of these functions also offer listening to changes via a standard Dart Stream

Session Delegate on the Watch

As mentioned the session also needs to be connected to from the watch app.

To do that add a new Swift File to create the delegate. And add the following code:

class FlutterWatchDelegate: NSObject, WCSessionDelegate {
  override init() {
    super.init()
    // Get the default session
    let session = WCSession.default
    // Set this instance as the delgate
    session.delegate = self
    // Activate the session
    session.activate()
  }

  func session(
    _ session: WCSession, activationDidCompleteWith activationState: WCSessionActivationState,
    error: (any Error)?
  ) {
    print("Activation Completed: \(session.activationState)")
    // Once connected you can initiate with initial data
  }
}

To use the delegate (and have the initialization logic called), add it as a variable in your watch app

@main
struct FlutterAppleWatchApp: App {
var delegate: FlutterWatchDelegate = FlutterWatchDelegate()

  var body: some Scene {
    WindowGroup {
      ContentView()
    }
  }
}

Share Data

There are multiple ways of sharing data between the phone app and the watch app.

Shared Application Context

Apple provides a way of having a shared application context which is a key‑value store between the apps on both phone and watch. Especially useful if you want to update data while not both apps are open at the same time.

Sending Data from Flutter to the Watch

The plugin offers a way to simply send a Map<String, dynamic> from Flutter to the Application Context.

final data = <String, dynamic>{'key': value};
await watchConnectivity.updateApplicationContext(data);

Receive Data on the Watch

The WCSessionDelegate has a function you can override which will get called when the ApplicationContext is updated.

class FlutterWatchDelegate: NSObject, WCSessionDelegate {
  // ...
  var myData: Int = 0
  
  // Override didReceiveApplicationContext to be called when the context gets updated
  func session(_ session: WCSession, didReceiveApplicationContext applicationContext: [String: Any]) {
    myData = applicationContext["key"] as Int?
  }
}

When the session is first activated you can also use the session to get the current application context as well.

func session(
  _ session: WCSession, activationDidCompleteWith activationState: WCSessionActivationState,
  error: (any Error)?
) {
  print("[WATCH] Activation Completed: \(session.activationState)")
  if session.activationState == WCSessionActivationState.activated {
    let initialContext = session.applicationContext
    // Use the context for what you need it
  }
}

Send Data from the Watch to Flutter

Sending Data the other way around is quite straightforward. In order to update the application context the other way around you can simply call updateApplicationContext on the session like this:

func updateData(value: Any?) {
  try? WCSession.default.updateApplicationContext(["key": value])
}

Receive Data from the Watch in Flutter

The plugin offers a way to get the applicationContext in Flutter both as a Future and a Stream

// As Future
final receivedContext = await watchConnectivity.getApplicationContext();

// Updates as a Stream
final updates = watchConnectivity.applicationContextUpdated
    .listen((applicationContext) {
      // Handle updates
    });  

Note that the received object has a currentContext and a receivedContext. This mirrors the underlying structure in the Swift API. This can get slightly confusing, especially when both the phone and the watch app are open at the same time and sending data both ways. So especially in these cases you should opt for different data exchange approaches.

For more details on the shared application context check out the Apple Documentation.

Sending Messages

One other ways for sharing data is sending messages in the form of Map<String, dynamic> around the two apps. Note that before sending you should check that the counterpart app is reachable . The syntax to use it so send receive messages is quite similar to sending application context

// Send Message from Flutter to Apple Watch
final messageData = <String, dynamic>{};
await watchConnectivity.sendMessage(messageData);

// Receive Data in Stream
watchConnectivity.messageReceived.listen((message) async {    
    /// New message is received, you can read it data map
    receivedMessageData = message.data;
});

Check out the plugin’s documentation on more Info and also on how to reply to messages

On the Apple Watch Site sending/receiving messages is also quite similar

// Override in Delegate for receiving messages
func session(
    _ session: WCSession,
    didReceiveMessage message: [String : Any]
) {
  // Handle received Message
}

// Sending Messages
func sendMessage(message: [String : Any]) {
  try? WCSession.default.sendMessage(message)
}

Check the Apple Documentation for more Info on sending Messages and receiving messages.

User Info

User Info is yet another way in which Apple allows you to send data as a Map<String, dynamic>. The main difference here is that Apple has slightly different rules on how receiving UserInfo can notify a backgrounded app, making User Info the prime candidate for using it to send data for complications. As a heads up I will write a follow up article on the topic of connecting Flutter with and Apple Watch App and Complications in another article so be sure to follow me for updates when this is out.

Sending Data works again quite similarly

await watchConnectivity.transferUserInfo({
    "key": "value"
});

Note: You may be tempted to use the parameter isComplication when you want to send data for a complication, however the underlying technology is not (yet) supported after apple switched complications to WidgetKit. However in my experiments updating the complication also worked without this. More on this in the follow up article

Receiving data from the watch is similarly done by overriding the respective function on the delegate. More Info again in Apple’s Documentation

func session(_ session: WCSession, didReceiveUserInfo userInfo: [String: Any] = [:]) {
  // Handle user Info for Complication
}

Files

WatchOS Connectivity also offers transferring files between platforms. This can be used to e.g send a screenshot of a Flutter Widget to display that on the watch (e.g your hero graphics) or also to transfer database files or backend responses. Sending a file is again following the other methods.

final baseDirectory = await getApplicationSupportDirectory();    
final file = File('${baseDirectory.path}/$myData.json');
final transfer = await watchConnectivity.transferFileInfo(file);

transfer?.setOnProgressListener((progress) {
  debugPrint('Progress: ${progress.currentProgress}');
});

Note that when receiving a File, this File is only available during the respective function invocation in the Watch App Delegate. So, in order to not lose it, you need to store it in the app’s document directory and use that copy when using the file outside of the function.

func session(_ session: WCSession, didReceive file: WCSessionFile) {
  let sourceURL = file.fileURL
  let fileManager = FileManager.default
  let documentsURL = fileManager.urls(for: .documentDirectory, in: .userDomainMask)[0]
  let destinationURL = documentsURL.appendingPathComponent(sourceURL.lastPathComponent)

  try? fileManager.moveItem(at: sourceURL, to: destinationURL)
    
  useFile()
}

To read the file e.g when the App connects to the session on the phone you can do something like:

func session(
  _ session: WCSession, activationDidCompleteWith activationState: WCSessionActivationState,
  error: (any Error)?
) {
  if session.activationState == WCSessionActivationState.activated {
    checkFile()
  }
}

var fileUrl : Url?


func checkFile() {
  let fileManager = FileManager.default
  let documentsURL = fileManager.urls(for: .documentDirectory, in: .userDomainMask)[0]
  let imageUrl = documentsURL.appendingPathComponent("myImage.png")

  if fileManager.fileExists(atPath: imageUrl.path()) {
    // File exists
    fileUrl = imageUrl
  } else {
    // File does not exist
    fileUrl = nil
  }
}

Display Data from Flutter in the Apple Watch App

So now that we have covered how to send data. Displaying data and updating the UI can be quite easy as well using the built-in state management solutions from SwiftUI. We can use the @Observable and @State annotation to automatically pass updates down to the UI Layer.

Observing the SessionDelegate

By using the @Observable annotation on the FlutterWatchDelegate it can get updates whenever a variable (in the example case the count changes)

// Mark as Observable for updates
@Observable
class FlutterWatchDelegate: NSObject, WCSessionDelegate {
  
  // Count variable
  var count: Int = 0

  override init() {
    super.init()
    let session = WCSession.default
    session.delegate = self
    session.activate()
  }

  func session(
    _ session: WCSession, activationDidCompleteWith activationState: WCSessionActivationState,
    error: (any Error)?
  ) {
    if session.activationState == WCSessionActivationState.activated {
      // Get initial count
      updateCount(applicationContext: session.applicationContext)
    }
  }

  // Update Count when new application context is received
  func session(_ session: WCSession, didReceiveApplicationContext applicationContext: [String: Any])
  {
    updateCount(applicationContext: applicationContext)
  }

  func updateCount(applicationContext: [String: Any]) {
    if let newCount = applicationContext["count"] as? Int {
      count = newCount
    }
  }
}

Using the delegate as State

Now that the FlutterWatchDelegate can be observed we can use it in the Watch Application to automatically receive updates

@main
struct FlutterAppleWatchApp: App {
  @State var delegate: FlutterWatchDelegate = FlutterWatchDelegate()

  var body: some Scene {
    WindowGroup {
      ContentView(
        delegate: delegate
      )
    }
  }
}

Using and displaying the data

Passing down the delegate to the View we can rebuild the ui with the value.

struct ContentView: View {
  let delegate: FlutterWatchDelegate

  var body: some View {
    List {
      // Using the count from the delegate
      // .description is the Swift equivalent of toString()
      Text(delegate.count.description)
      Button(
        "Increment",
        action: delegate.incrementCounter
      )     
    }
  }
}

As you can see in the example above we call an incrementCounter method on the delegate. This is an easy way to enable two way data transfers as described in the previous section.

The respective method on the delegate may look something like this

func incrementCounter() {
  count = count + 1

  try? WCSession.default.updateApplicationContext(["count": count])
}

Things to look out for

There are a couple of issues that may arise that could stop you from building the app (especially in release mode)

Ensure the “Thin Binary” phase happens after “Embed Watch Content”

Drag the Thin Binary step after the Embed Watch Content step in Runner > Build Phases

Ensure Watch Target Build Settings target the correct Platform

There is an issue where Flutter overrides the Watch Platform and can then not correctly build the App.

To work around this you have to manually set the Watch App > Build Settings > Supported Platforms for Profile and Release builds to watchOS

Closing thoughts

While the initial setup can be a bit finicky and working around Xcode build errors is certainly not fun, this process shows that Watch Companion Apps for Flutter Apps is possible.

Does this mean you should all build Watch Companion Apps right away? Maybe! It all depends on your app’s use cases and, crucially, if it is something that brings a benefit to your users?

In the end a Flutter App is installed just like a native app. So we can use all the benefits of Flutter (write code once run it anywhere, Hot Reload, …) plus use the APIs for platform integration combined with the vast ecosystem on pub.dev to make the best use of platform specific features to provide the best User Experience possible!

—

Follow me here or on Social Media to get notified when the second part of this article is published about adding Complications

Bluesky

Anton (@abausg.bsky.social)

Twitter

Anton Borries (@ABausG) on X

Consider sponsoring to support my work

Sponsor @ABausG on GitHub Sponsors

Example App

GitHub - ABausG/flutter_apple_watch_talk: Talk about Flutter on Apple Watch

This article will guide you through the process of implementing configurable iOS Home Screen Widgets in your Flutter application using the home_widget package.

For this we will make use of WidgetConfigurationIntent, Apple’s newer and recommended way of writing configurable widgets. home_widget also supports the older SiriKit intent. Documentation for this can be found in the home_widgets docs.

Prerequisites:

Before we begin, ensure you have added the home_widget plugin as a dependency in your pubspec.yaml file. For this guide, we'll assume you're using version ^0.8.0.

dependencies:
  flutter:
    sdk: flutter
  home_widget: ^0.8.0

Run flutter pub get to fetch the dependency.

We’ll be spending most of our time in Xcode. For that open the iOS workspace in Xcode.

Step 1: Creating Your Widget Extension with Configuration Intent

The first step is creating a new WidgetExtension and adding that to the App

• Navigate to File> New > Target
• Select Widget Extension
• Crucially, check the box for Include Configuration App Intent.

Upon creation, Xcode will generate the foundational files for your widget, including:

• AppIntentTimelineProvider: This class is responsible for providing a timeline of widget updates. When using WidgetConfigurationIntent, it utilizes an AppIntent for configuration.
• TimelineEntry: This struct represents the data that will be displayed in your widget at a specific point in time. It always includes a date field to schedule updates.
• Your Widget’s View (built with SwiftUI): This defines the visual presentation of your widget.
• Your Widget’s main Widget struct: Pay close attention to the kind property you define here, as this identifier will be used later in your Flutter code to reference and update this specific widget.

In a separate Swift file (likely named YourWidgetNameIntent.swift or within AppIntent.swift), you'll find a ConfigurationAppIntent: WidgetConfigurationIntent protocol definition. This is where you'll define the configurable options for your widget.

Step 2: Adjusting the Configuration Intent

The generated ConfigurationAppIntent class is for defining the customizable aspects of your widget. To add a configuration field, simply declare a property with the @Parameter attribute:

@available(iOS 17.0, *)
struct ConfigurationAppIntent: WidgetConfigurationIntent {
  static var title: LocalizedStringResource = "Configuration"
  static var description = IntentDescription("This is an example widget.")

  // An example simple parameter
  @Parameter(title: "Name", default: "World")
  var name: String

  func perform() async throws -> Never {
    return Never()
  }
}

In this example, we’ve added a name parameter with a default value of "World". This will appear as a text field in the widget's configuration options when the user adds or edits the widget.

Accessing these configuration values within your widget’s UI is straightforward:

struct ConfigurableWidgetEntryView : View {
    var entry: Provider.Entry
    var body: some View {
        VStack {
            Text("Hello")
            Text(entry.configuration.name)
        }
    }
}

Here, entry.configuration.name retrieves the value the user has set in the configuration.

Step 3: Getting Data from Flutter to the Configuration

Often, you’ll want to provide dynamic configuration options based on data within your Flutter app. The home_widget plugin allows you to save data that can be used in your widget's configuration panel using HomeWidget.saveWidgetData

In order to enable synchronisation between Flutter, the iOS App and the Widget you need to register an App Group. For this you need a paid Apple Developer account.

1. Register a new App Group on the Apple Developer Portal
2. Add the App Group Capability to both the App and the WidgetExtension
   Runner > Signing & Capabilities > + Capability > App Groups
   ConfigurableWidgetExtension > Signing & Capabilities > + Capability > App Groups
3. Register the App Group with home_widget in Flutter
   await HomeWidget.setAppGroupId(‘group.com.example.appgroup’);

final punctuations = [
    '!',
    '!!!',
    '.',
    '?',
    // Wave Emoji
    '\u{1F44B}',
];
await HomeWidget.saveWidgetData(
    'punctuations',
    jsonEncode(punctuations),
);

In this Dart code, we’re saving a list of punctuations as a JSON string with the key 'punctuations'. But you could also use this to provide a list of locations for weather or a list of to-do lists.

Using Flutter Values as Options in the Customize Panel

To make these saved values appear as selectable options in the widget’s configuration, you need to define an AppEntity and a corresponding EntityQuery in your Swift code:

@available(iOS 17.0, *)
struct ConfigurationAppIntent: WidgetConfigurationIntent {
  ...

  @Parameter(title: "Punctuation")
  var punctuation: PunctuationEntity
}

// Make Entity Codable so home_widget
// That way home_widget can best extract the values from a configuration
struct PunctuationEntity: AppEntity, Codable {
  let id: String
  static var typeDisplayRepresentation: TypeDisplayRepresentation = "Punctuation"
  static var defaultQuery = PunctuationQuery()
  var displayRepresentation: DisplayRepresentation {
      DisplayRepresentation(title: "\(id)")
  }
}

struct PunctuationQuery: EntityQuery {
  func punctuations() -> [PunctuationEntity] {
    let userDefaults = UserDefaults(suiteName: "YOUR_APP_GROUP")
      do {
        let jsonPunctuations = (userDefaults?.string(forKey: "punctuations") ?? "[\"!\"]").data(
          using: .utf8)!
        let stringArray = try JSONDecoder().decode([String].self, from: jsonPunctuations)
        return stringArray.map { punctuation in
          PunctuationEntity(id: punctuation)
        }
      } catch {
        return [PunctuationEntity(id: "!")]
      }
  }

  func entities(for identifiers: [PunctuationEntity.ID]) async throws -> [PunctuationEntity] {
      let results = punctuations().filter { identifiers.contains($0.id) }
      return results
  }

  func suggestedEntities() async throws -> [PunctuationEntity] {
      return punctuations()
  }

  func defaultResult() async -> PunctuationEntity? {
      try? await suggestedEntities().first
  }
}

Here’s what’s happening:

• PunctuationEntity: This struct conforms to AppEntity. It represents a single punctuation option with an id. The displayRepresentation defines how this entity will be displayed to the user in the configuration panel. Codable is used for home_widget to easily parse this value again so it can be read again from within Flutter to detect which option a user chose.
• PunctuationQuery: This struct conforms to EntityQuery. Its methods are responsible for fetching the available punctuation options.
• punctuations(): This function retrieves the JSON string we saved from Flutter using UserDefaults(make sure to use your App Group suite name) and decodes it into an array of PunctuationEntityobjects.
• entities(for identifiers:): This function fetches specific entities based on their IDs.
• suggestedEntities(): This provides a list of suggested entities for the configuration.
• defaultResult(): This sets a default entity if the user doesn't make a selection.

Now you can access the selected punctuation in your widget’s code:

struct ConfigurableWidgetEntryView: View {
  var entry: Provider.Entry
  var body: some View {
    VStack {
      Text("Hello")
      Text(entry.configuration.name)
      Text(entry.configuration.punctuation.id)
    }
  }
}

Step 4: Seeing Configuration in Flutter

To access the user’s widget configurations within your Flutter app, you need to establish a connection between your AppIntent and the App.

Adding Runner as a Target of the Widget

Open your Intent Swift file (e.g., YourWidgetNameIntent.swift or AppIntent.swift) in Xcode. In the Details Pane(usually on the right), find the Target Membership section and enable the Runner target for this file.

Registering Configuration in AppDelegate

In your Flutter project’s ios/Runner/AppDelegate.swift file, import the home_widget plugin and register your ConfigurationAppIntent with the corresponding widget kind:

import Flutter
import UIKit
import home_widget

@main
@objc class AppDelegate: FlutterAppDelegate {
override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    if #available(iOS 17.0, *) { 
      HomeWidgetPlugin.setConfigurationLookup(to: [
        "ConfigurableWidget": ConfigurationAppIntent.self
      ])
    }
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

Replace "ConfigurableWidget" with the actual kind you defined in your widget's main Swift file.

Now, within your Flutter code, you can retrieve the configurations of all installed widgets using HomeWidget.getInstalledWidgets():

final configuration = await HomeWidget.getInstalledWidgets();

This will return a list of HomeWidgetInfo objects. Each HomeWidgetInfo contains a Map<String, dynamic>? configuration property, which holds the user's settings for that specific widget.

{
    "name": "Documentation",
    "punctuation": {
        "id": "!!!"
    }
}

On iOS Simulators, HomeWidget.getInstalledWidgets() will always return an empty list. To fully test the configuration retrieval, you must test on a real iOS device.

Conclusion

By leveraging WidgetConfigurationIntent with the home_widget plugin, you can create powerful and personalized Home Screen Widgets for your iOS users. This approach provides a clean and efficient way to offer customization options, enhancing the engagement and utility of your widgets. Remember to test thoroughly on a physical device to experience the full functionality of configurable widgets.

Do you like this article and my work? Consider supporting via Github Sponsors

Sponsor @ABausG on GitHub Sponsors

More Info on home_widget and configurable widgets

Documentation

Configurable Widgets

Example App

https://github.com/abausg/home_widget/tree/main/examples/configurable_widgets

home_widget on pub.dev

home_widget | Flutter package

In this article we’ll take a look at the home_widget_counter App created for iOS Interactivity and add another Android Widget now using Glance technology.

Scroll down to the end to see what else is new in home_widget

Quick Summary of the Flutter Part of the App

The App is basically the classic Flutter Counter App. When counting up the App uses home_widget to store the count and updates the Home Screen Widget.

The method that is invoked looks like this:

Future<void> _sendAndUpdate([int? value]) async {
  await HomeWidget.saveWidgetData(_countKey, value);
 
  await HomeWidget.updateWidget(
    iOSName: 'CounterWidget',
    androidName: 'CounterWidgetProvider',
  );
}

For this to work you’ll need the latest Versions of home_widget.

# For Flutter Stable
home_widget: ^0.5.0

# For Flutter Beta
home_widget: ^0.6.0

Writing the Jetpack Compose Widget

Prepare Gradle File

Jetpack Glance requires us a bit of adjustments to the Gradle File in order to compile the App:

1. Add Glance Dependency to the build.gradle File in your app directory

dependencies {
 implementation ‘androidx.glance:glance-appwidget:1.0.0’
}

2. Enable Compose Support. Note that depending on your kotlin version you might have to also adjust the compose option.

buildFeatures {
  compose true
}

// For the example this is needed with defining the Kotlin Version to 1.9.20
composeOptions {
  kotlinCompilerExtensionVersion = "1.5.4"
}

Add this point it might be best to quickly run your app to ensure that the app still compiles and runs.

Add the necessary Files

We’ll need to create the following files

• A configuration xml file
• A WidgetReceiver
• The actual Widget
• We also need to define the Configuration File and the Receiver in the App’s Manifest file

The configuration file needs to be created in android/app/src/main/res/xml . In there you can customized and configure options like min/max sizes and loading behaviour. For our Counter example it looks like this:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:initialLayout="@layout/glance_default_loading_layout"
    android:minWidth="203dp"
    android:minHeight="90dp"
    android:resizeMode="horizontal|vertical"
    android:updatePeriodMillis="10000" />

The WidgetReceiver is handling the updating behavior of the widget. home_widget offers an abstraction for this so you only need to provide simple references to the Widget (which will be created in the next step). Thanks to these abstractions for our example the file is super short:

import HomeWidgetGlanceWidgetReceiver

class CounterGlanceWidgetReceiver : HomeWidgetGlanceWidgetReceiver<CounterGlanceWidget>() {
    override val glanceAppWidget = CounterGlanceWidget()
}

The WidgetReceiver is already referencing the final file our AppWidget. This is whats actually building the Widget. Using Jetpack Compose the syntax with which you can now write the widgets is a lot closer to how you would write Flutter UI Code:

class CounterGlanceWidget : GlanceAppWidget() {

    // Needed for Updating   
    override val stateDefinition = HomeWidgetGlanceStateDefinition()

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        provideContent {
            GlanceContent(context, currentState())
        }
    }

    @Composable
    private fun GlanceContent(context: Context, currentState: HomeWidgetGlanceState) {
        val data = currentState.preferences
        val count = data.getInt("counter", 0)

        Box(modifier = GlanceModifier.background(Color.White).padding(16.dp).clickable(onClick = actionStartActivity<MainActivity>(context))) {
            Column(
                    modifier = GlanceModifier.fillMaxSize(),
                    verticalAlignment = Alignment.Vertical.CenterVertically,
                    horizontalAlignment = Alignment.Horizontal.CenterHorizontally,
            ) {
                Text(
                        "You have pushed the button this many times:",
                        style = TextStyle(fontSize = 14.sp, textAlign = TextAlign.Center),
                )
                Text(
                        count.toString(),
                        style = TextStyle(fontSize = 24.sp, fontWeight = FontWeight.Bold, textAlign = TextAlign.Center),
                )

            }
        }
    }
}

Please take special note of the override val stateDefinition = HomeWidgetGlanceStateDefinition() as this is vital for home_widget to update the widget’s UI

As a last step we need to tell our App about our new Widget in the Android Manifest file. Here we tie together the Configuration File and the Widget Receiver. Simply add this block inside the application section of the manifest file:

<receiver
    android:name=".CounterGlanceWidgetReceiver"
    android:label="Glance"
    android:exported="true">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data
        android:name="android.appwidget.provider"
        android:resource="@xml/counter_glance_widget" />
</receiver>

That’s it. Now you should be able to add the Widget to your Home Screen and see the current Count!

Updating the Widget

Going from the example we need to adjust (or add) the HomeWidget.updateWidget method to now target our new CounterGlanceWidgetReceiver

Future<void> _sendAndUpdate([int? value]) async {
  await HomeWidget.saveWidgetData(_countKey, value);
 
  await HomeWidget.updateWidget(
    iOSName: 'CounterWidget',
    androidName: 'CounterGlanceWidgetReceiver',
  );
}

Adding Interactivity

Next up we want to add interactivity to the widget such that we can count up directly from the HomeScreen.

Preparing the Flutter App

On the Flutter side of things we need to register an interactivity callback that will then increment the count and update the widget again. Important thing to note are that the interactive callback is accessible statically and marked with @pragma(‘vm:entry-point’)

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
 await HomeWidget.registerInteractivityCallback(interactiveCallback);
  runApp(const MyApp());
}

@pragma('vm:entry-point')
Future<void> interactiveCallback(Uri? uri) async {
  // We check the host of the uri to determine which action should be triggered.
  if (uri?.host == 'increment') {
    await _increment();
  } else if (uri?.host == 'clear') {
    await _clear();
  }
}

/// Saves that new value
Future<int> _increment() async {
  final oldValue = await _value;
  final newValue = oldValue + 1;
  await _sendAndUpdate(newValue);
  return newValue;
}

/// Clears the saved Counter Value
Future<void> _clear() async {
  await _sendAndUpdate(null);
}

/// Stores [value] in the Widget Configuration
Future<void> _sendAndUpdate([int? value]) async {
  await HomeWidget.saveWidgetData(_countKey, value);
  await HomeWidget.updateWidget(
    iOSName: 'CounterWidget',
    androidName: 'CounterGlanceWidgetReceiver',
  );
}

Adjusting the Glance UI

Glance supports interactivity using ActionCallbacks let’s create action callbacks for the increment and the clear action.

class IncrementAction : ActionCallback {
    override suspend fun onAction(context: Context, glanceId: GlanceId, parameters: ActionParameters) {
        val backgroundIntent = HomeWidgetBackgroundIntent.getBroadcast(
                context,
                Uri.parse("homeWidgetCounter://increment"))
        backgroundIntent.send()
    }
}

class ClearAction : ActionCallback {
    override suspend fun onAction(context: Context, glanceId: GlanceId, parameters: ActionParameters) {
        val backgroundIntent = HomeWidgetBackgroundIntent.getBroadcast(
                context,
                Uri.parse("homeWidgetCounter://clear"))
        backgroundIntent.send()
    }
}

To use these Actions in the UI we need to add a GlanceModifier to the Elements that we want to invoke these Actions with.

Box(
  modifier = GlanceModifier.clickable(onClick = actionRunCallback<IncrementAction>())
) {
  Image(
    provider = ImageProvider(R.drawable.baseline_add_24), contentDescription = null,
    colorFilter = ColorFilter.tint(ColorProvider(Color.White)),
    modifier = GlanceModifier.size(32.dp).background(
      imageProvider = ImageProvider(R.drawable.fab_shape)
    )
  )
}

So now our GlanceContent looks like this to include our Buttons

  @Composable
  private fun GlanceContent(context: Context, currentState: HomeWidgetGlanceState) {
    val data = currentState.preferences
    val count = data.getInt("counter", 0)

    Box(modifier = GlanceModifier.background(Color.White).padding(16.dp).clickable(onClick = actionStartActivity<MainActivity>(context))) {
      Column(
          modifier = GlanceModifier.fillMaxSize(),
          verticalAlignment = Alignment.Vertical.CenterVertically,
          horizontalAlignment = Alignment.Horizontal.CenterHorizontally,
      ) {
        Text(
            "You have pushed the button this many times:",
            style = TextStyle(fontSize = 14.sp, textAlign = TextAlign.Center),
        )
        Spacer(GlanceModifier.defaultWeight())
        Text(
            count.toString(),
            style = TextStyle(fontSize = 32.sp, fontWeight = FontWeight.Bold, textAlign = TextAlign.Center),
        )
        Spacer(GlanceModifier.defaultWeight())
        Row(
            modifier = GlanceModifier.fillMaxWidth()
        ) {
          Box(
              modifier = GlanceModifier.clickable(onClick = actionRunCallback<ClearAction>())
          ) {
            Image(
                provider = ImageProvider(R.drawable.baseline_close_24), contentDescription = null,
                colorFilter = ColorFilter.tint(ColorProvider(Color.White)),
                modifier = GlanceModifier.size(32.dp).background(
                    imageProvider = ImageProvider(R.drawable.fab_shape)
                )
            )
          }
          Spacer(GlanceModifier.defaultWeight())
          Box(
              modifier = GlanceModifier.clickable(onClick = actionRunCallback<IncrementAction>())
          ) {
            Image(
                provider = ImageProvider(R.drawable.baseline_add_24), contentDescription = null,
                colorFilter = ColorFilter.tint(ColorProvider(Color.White)),
                modifier = GlanceModifier.size(32.dp).background(
                    imageProvider = ImageProvider(R.drawable.fab_shape)
                )
            )
          }
        }
      }
    }
  }

In order for the App to know that it can handle the home_widget background workers we need to add the following section to the App’s Manifest.

<receiver
    android:name="es.antonborri.home_widget.HomeWidgetBackgroundReceiver"
    android:exported="true">
    <intent-filter>
        <action android:name="es.antonborri.home_widget.action.BACKGROUND" />
    </intent-filter>
</receiver>

<service
    android:name="es.antonborri.home_widget.HomeWidgetBackgroundService"
    android:exported="true"
    android:permission="android.permission.BIND_JOB_SERVICE" />

That’s it. Now we can can increment and clear the counter directly from the HomeScreen!

More new Features in home_widget 0.5.0

Pinning Home Screen Widgets

As an additional new feature home_widget now supports pinning a Widget to the Home Screen directly from the App. This feature is only available on Android (if the User’s launcher supports it)

To request to pin the widget simply invoke HomeWidget.requestPinWidget()

Future<void> _requestToPinWidget() async {
  final isRequestPinSupported = await HomeWidget.isRequestPinWidgetSupported();
  if (isRequestPinSupported == true) {
    await HomeWidget.requestPinWidget(androidName: 'CounterGlanceWidgetReceiver');
  }
}

Widgets Analytics

You can now get information about the widgets a user currently has installed/pinned on their Home or Lock Screens. This is extremely useful for analytics and/or if you want to reward your users if they install your Widget.

To query the currently installed widgets of your app simply call

Future<void> _checkInstalledWidgets() async {
  final installedWidgets = await HomeWidget.getInstalledWidgets();  debugPrint(installedWidgets.toString());
}

// Output Android:
I/flutter (28322): [HomeWidgetInfo{iOSFamily: null, iOSKind: null, androidWidgetId: 22, androidClassName: .CounterGlanceWidgetReceiver, androidLabel: Glance}]

// Output iOS (HomeScreen and LockScreen):
flutter: [HomeWidgetInfo{iOSFamily: systemSmall, iOSKind: CounterWidget, androidWidgetId: null, androidClassName: null, androidLabel: null}, HomeWidgetInfo{iOSFamily: accessoryCircular, iOSKind: CounterWidget, androidWidgetId: null, androidClassName: null, androidLabel: null}]

Closing

Thanks so much to all of the contributors in this new release.

home_widget on pub.dev and on github.com

If you or your company is benefitting from home_widget consider sponsoring me on GitHub

Sponsor @ABausG on GitHub Sponsors

You can find the code for this example on Github

GitHub - ABausG/home_widget_counter: An example App for home_widget rebuilding the Flutter Counter App as a HomeScreen Widget

If you have any questions about home_widget feel free to reach out to me on X/Twitter

https://twitter.com/ABausG

Styling Material Widgets can be tricky. Using the widgetbook_base_components mason brick you can get an overview inside Widgetbook how they will look, feel and behave

Struggling with styling ThemeData

Personally I am a big fan of using the default Material Widgets in Flutter Apps as they are easy to use, offer great support for Accessibility and relying on theme is great if you are onboarding new team members as they can just use the default blocks without having to make sure they use the correct widget.

However one big caveat with this can be what Mike Rydstrom put into great words during his workshop at Flutter & Friends (Material for the Workshop can be found here)

Flutter Material theming is fun and easy — but tedious

This really resonated with me as that basically reflects my experience with it. Adjusting ThemeData to match a given Design or just to your preference can indeed be tricky to get all the nuances right. However things like Mike’s Theme Playground and flex_color_scheme can really help you nail your ThemeData. When you have your Theme just right and you are able to just use Material Widgets without having to do custom styling when using them it feels great to use, is quick and ensures visual consistency between your uses of these Widgets.

The idea

widgetbook_base_components is a mason brick that generates UseCases for your Widgetbook to show you how these widgets would appear and behave in your App.

In the first version the following components are supported: Buttons, TextStyles, Controls, Card, AlertDialog, Indicators, Chips, TextFields, ListTile, BottomNavigationBar

You might notice that these UseCases in Widgetbook have a lot more info than you are normally used to. This is because the idea behind widgetbook_base_components is to get a quick overview of how certain Material Widget Groups like buttons/switches/etc behave if used in an app only relying on the style set by the encapsulting ThemeData.

For some examples you can also check out a Widgetbook with these components here:

https://abausg.github.io/bricks/widgetbook_base_components/web/

Using the brick

Note: I am assuming you already have setup Widgetbook in your project. If not check out the official documentation https://docs.widgetbook.io/

1. Follow the installation steps for mason if you haven’t by running
   dart pub global activate mason_cli
   mason init
2. Add the widgetbook_base_components brick using
   mason add widgetbook_base_components
3. "Make" the brick using mason make widgetbook_base_components
4. Run dart run build_runner build (ignore this if you are using watch )
5. Check your Widgetbook for the new Base Components 🎉

Next Steps

I think seeing the different Variants side by side offers a great way of grasping how your App might look for the provided ThemeData

I am well aware that this is only a small subset of Material Widgets that are supported but I think it is a great start. If you are missing a specific Widget feel free to open a PR.

For thoughts or any more questions reach out to me on X/Twitter

Thanks

Many thanks to Roaa, Lucas and Tim from Widgetbook for the Feedback on the Brick.

Also big thanks to Mike! His work for everything Material is phenomenal and his Theme Playground was a huge inspiration for this. You should follow him on X/Twitter to always get the latest news about Material and Flutter!

JavaScript is not available.

Code for the Brick:

https://github.com/ABausG/bricks/tree/main/bricks/widgetbook_base_components

Example of the Widgetbook:

https://abausg.github.io/bricks/widgetbook_base_components/web/

Getting Material Base Components into Widgetbook was originally published in Widgetbook on Medium, where people are continuing the conversation by highlighting and responding to this story.

This sparked the idea of checking if it is possible to use my package home_widget to create a Lockscreen widget with the best bird mascot there is

Turns out it is super easy!

Note the following steps build upon the Counter App/Widget created in this Article for interactive widgets

Creating the Widget Image

To create the Widget I am using the renderFlutterWidget method of home_widget to save a Flutter Widget as an image to use in the native widget.

For this I used one of the Dash illustrations by Alex Bradt created for the F3 event and added the current counter value on top (with a bit of eyeballed transformation).

Stack(
  children: [
    Positioned.fill(
      child: Padding(
        padding: const EdgeInsets.all(30.0),
        child: Image.asset('assets/dash_sign_small.png'),
      ),
    ),
    Transform.rotate(
      angle: 5 * pi / 180,
      child: Transform.translate(
        offset: const Offset(58, 29),
        child: SizedBox(
          height: 100,
          width: 134,
          child: Padding(
            padding: const EdgeInsets.all(16.0),
            child: FittedBox(
              fit: BoxFit.contain,
              child: Center(
                child: Text(
                  count.toString(),
                  style: const TextStyle(
                    fontWeight: FontWeight.bold,
                    fontSize: 70,
                    color: Colors.white,
                  ),
                  textAlign: TextAlign.center,
                ),
              ),
            ),
          ),
        ),
      ),
    ),
  ],
)

When updating the value I save a rendering of that Widget using renderFlutterWidget

await HomeWidget.renderFlutterWidget(
  DashWithSign(count: value ?? 0),
  key: 'dash_counter',
  logicalSize: const Size(100, 100),
);

Overall I think especially for smaller Widgets like this the renderFlutterWidget method is ideal for Flutter developers as I would assume most of us are way more efficient to write intricate widgets like this in Flutter than building things like this in SwiftUI.

When using this make sure to keep the following points in mind:

1. You should check how your Widget looks after iOS applies the tinting on the Lockscreen as it will adjust it to a uniform color that might also be influenced by the wallpaper of the user.
2. Remember that for the some configurations iOS will clip the widget to a circle so make sure that you add adequate padding to your widget

The native part

Writing native iOS code can be scary but if you managed to get through the example for the counter app you should nail this! Especially as the Widget itself is super easy when using a rendered Flutter Widget

Add the supported family

In iOS Lockscreen Widgets are called AccessoryWidgets and can be added as a supportedFamily to your WidgetConfiguration

var body: some WidgetConfiguration {
  ...
  .description("Count the Number Up")
  .supportedFamilies([
      .systemSmall,
      .systemMedium,
      .accessoryCircular
  ])

The important family here is .acessoryCircular Here you can also define which sizes you want to support in general. For a list of all possible families check this page by Apple.

Adjust the Layout for the Widget

When building the Widget we need to detect which widgetFamily we are building and in that case return our pre rendered Image.

struct CounterWidgetEntryView: View {
  var entry: Provider.Entry

  // Detect the current Family
  @Environment(\.widgetFamily) var family
    
  var body: some View {
    if family == .accessoryCircular {
      Image(
        uiImage: UIImage(
          contentsOfFile: UserDefaults(suiteName: "YOUR_APP_GROUP")?.string(
            forKey: "dash_counter") ?? "")!
      ).resizable()
        .frame(width: 76, height: 76)
        .scaledToFill()
    } else {
     // Build Widget for other families
    }
  }
}

Thats already it. Now if you run the App you should be able to add the widgets to your HomeScreen.

You could of course also create a new Widget Target for the widgets if you want to add more

Conclusion

All in all extending your App to the iOS lockscreen is super quick (especially if you are already using home_widget) and allows you to give users access to your Apps even more.

Links

The full repository of this example is here:

GitHub - ABausG/home_widget_counter: An example App for home_widget rebuilding the Flutter Counter App as a HomeScreen Widget

With the changes made for this article in this commit.

If you have any questions regarding this feel free to reach out to me on Twitter/X

Check out/Like home_widget on pub.dev

home_widget | Flutter package

Check out/Star Open PRs/Issues for home_widget on github

GitHub - ABausG/home_widget: Flutter Package for Easier Creation of Home Screen Widgets

Check out Alex Bradt who did the amazing Dash Illustration

JavaScript is not available.

While building several Flutter Apps in the past that use ApptiveGrid as a Data Source we realized that we could use the power of ApptiveGrid and our suite of ApptiveGrid Flutter Packages to build tools for development and quality insurance of Flutter Apps.

We are already using several of these tools in the apps we are building and we are excited to announce that we are open sourcing the first package now. apptive_grid_error_reporting is a little tool to easily report errors to an ApptiveGrid Space

Why another error reporting tool?

Of course there are lots of options in the space of error reporting that all have their place. However we noticed that for our apps — often time for small customers — these solutions and associated costs are not always a great fit.

Another point is obviously that we want to use ApptiveGrid more ourselves. So while exploring options on how we can incorporate ApptiveGrid in more of our day to day work we quickly realized that we can build a lightweight and customizable solution for basic error reporting that is also GDPR compliant.

Setting it up

1. Create a new Space to your ApptiveGrid Account using this template. (If you don’t have an ApptiveGrid Account yet you can create one in the process. It’s free)
2. Go to the reporting form and copy the link from the share men

3. Add apptive_grid_error_reporting to you pubspec dependencies and create a reporting Instance using the form link

final reporting = ApptiveGridErrorReporting(
  reportingForm: Uri.parse('FORM_LINK'),
  project: 'myProject',
);

That’s already it all in terms of setting everything up.

Reporting Errors

To report errors simply call

reporting.report(error);

Optionally you can provide more Information like a StackTrace or a custom message to better figure out where the error occurred.

reporting.report(
  error,
  stackTrace: StackTrace.current,
  message: 'Error when doing a demo',
);

If you want to track down what a user might have done leading up to the error you can simply add some log entries.

reporting.log(‘Something was clicked’);

These logs will be added to the reports inside ApptiveGrid as a .txt file for your error analysis

Creating custom Views

In ApptiveGrid you can view your data not only as a Grid but also create custom views based on your needs. In this next example I can show you how quick it is to create a simple Kanban view for all the issues.

1. Create a Kanban View

2. Select the “Status” Field as the default field

3. Enable the column for ungrouped entries

You now have a Kanban Board right inside of ApptiveGrid for all reported errors where you can move cards just like with any other view. You can customize these views by playing around with custom filters or sorting.

Using ApptiveGrid Workflows

ApptiveGrid offers custom workflows that can be used to get more out of your error reports. In this next example I’ll show you how quickly you can set up custom Slack Notifications whenever there is a new error reported

1. Go to the Workflows Tab inside your ApptiveGrid and create a new flow

2. Select “New Entry” as your trigger. Configure to use the Reporting Grid as the source

3. Add a “Slack” action

• If you “test the action” the fields panel will be populated with placeholder tokens that you can then use to create custom slack messages that report new errors

• Add your Slack Webhook Url

Further customisation

In this article I have only shown how to add custom views and use a simple workflow to report errors on Slack. However you can customize the whole reporting even further. For example you could add an “Assigned” Field to your grid and automatically send an email to the assigned developer using a workflow when you change the value or anything in the field by playing around with the trigger conditions inside the flow.

Also using the Http Call Node you can integrate with a lot of other services/products that you are already using for example to create tickets inside Jira or Github. If you have a need for a more specialized Workflow Node

Closing

If you want a simple and lightweight error reporting tool we encourage you to try out apptive_grid_error_reporting. Also if you want to use ApptiveGrid for the backend of your Apps check out our other ApptiveGrid Flutter Packages.

Resources

Package on pub.dev:

apptive_grid_error_reporting | Flutter Package

ApptiveGrid on LinkedIn:

ApptiveGrid | LinkedIn

ApptiveGrid on X/Twitter:

JavaScript is not available.

Anton on X/Twitter:

Building Flutter Dev Tools with ApptiveGrid — Error Reporting was originally published in apptivegrid on Medium, where people are continuing the conversation by highlighting and responding to this story.

Prerequisites

This Article assumes that you know the basics of adding HomeScreen Widgets with home_widget. If you want more details on how to set things up initially please check out the README as well as have a look at the Codelab

Dart Setup

Please note that as of writing this article iOS Interactivity is only available as a pre-release version of home_widget 0.4.0-alpha.0 This will change once Apple officially releases iOS 17 and XCode 15. Once that is fully released I will update this Article accordingly

While this is in pre-release add this to your pubspec.yaml file

home_widget: 0.4.0-alpha.0

Building the Counter App

We only are doing slight modifications to the generated counter app. Mainly we will use static functions to save/update/restore the current count, as this will make our work to use in the interactive callback a lot easier. You should obviously not move all of your business logic into static functions in your real apps but for this example it will be fine.

We will use HomeWidget.getWidgetData for getting the current value. HomeWidget.saveData to save the new value and HomeWidget.updateWidget

In the context it looks like this

const _countKey = 'counter';

/// Gets the currently stored Value
Future<int> get _value async {
  final value = await HomeWidget.getWidgetData<int>(_countKey, defaultValue: 0);
  return value!;
}

/// Retrieves the current stored value
/// Increments it by one
/// Saves that new value
/// @returns the new saved value
Future<int> _increment() async {
  final oldValue = await _value;
  final newValue = oldValue + 1;
  await _sendAndUpdate(newValue);
  return newValue;
}

/// Clears the saved Counter Value
Future<void> _clear() async {
  await _sendAndUpdate(null);
}

/// Stores [value] in the Widget Configuration
Future<void> _sendAndUpdate([int? value]) async {
  await HomeWidget.saveWidgetData(_countKey, value);
  await HomeWidget.updateWidget(
    iOSName: 'CounterWidget',
    androidName: 'CounterWidgetProvider',
  );
}

Adding an Interactivity callback

To get interactivity working in the dart part we need to create and register an interactivity callback. This callback has 2 requirements. It needs to be static as well as public and needs to be annotated with @pragma(‘vm:entry-point’) . It will be called with an Uri to detect what element triggered the callback. In our example the callback looks like this

@pragma('vm:entry-point')
Future<void> interactiveCallback(Uri? uri) async {
  // We check the host of the uri to determine which action should be triggered.
  if (uri?.host == 'increment') {
    await _increment();
  } else if (uri?.host == 'clear') {
    await _clear();
  }
}

Lastly we need to register that callback. Please note that you should call this after you have setup the AppGroupId for iOS. In our case we just do it in the main method.

await HomeWidget.registerInteractivityCallback(interactiveCallback);

With this our main File should look something like this:

import 'package:flutter/material.dart';
import 'package:home_widget/home_widget.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // Set AppGroup Id. This is needed for iOS Apps to talk to their WidgetExtensions
  await HomeWidget.setAppGroupId('YOUR_GROUP_ID');
  // Register an Interactivity Callback. It is necessary that this method is static and public
  await HomeWidget.registerInteractivityCallback(interactiveCallback);
  runApp(const MyApp());
}

/// Callback invoked by HomeWidget Plugin when performing interactive actions
/// The @pragma('vm:entry-point') Notification is required so that the Plugin can find it
@pragma('vm:entry-point')
Future<void> interactiveCallback(Uri? uri) async {
  // We check the host of the uri to determine which action should be triggered.
  if (uri?.host == 'increment') {
    await _increment();
  } else if (uri?.host == 'clear') {
    await _clear();
  }
}

const _countKey = 'counter';

/// Gets the currently stored Value
Future<int> get _value async {
  final value = await HomeWidget.getWidgetData<int>(_countKey, defaultValue: 0);
  return value!;
}

/// Retrieves the current stored value
/// Increments it by one
/// Saves that new value
/// @returns the new saved value
Future<int> _increment() async {
  final oldValue = await _value;
  final newValue = oldValue + 1;
  await _sendAndUpdate(newValue);
  return newValue;
}

/// Clears the saved Counter Value
Future<void> _clear() async {
  await _sendAndUpdate(null);
}

/// Stores [value] in the Widget Configuration
Future<void> _sendAndUpdate([int? value]) async {
  await HomeWidget.saveWidgetData(_countKey, value);
  await HomeWidget.updateWidget(
    iOSName: 'CounterWidget',
    androidName: 'CounterWidgetProvider',
  );
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData.light(
        useMaterial3: false,
      ),
      home: const MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
  }

  Future<void> _incrementCounter() async {
    await _increment();
    setState(() {});
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    super.didChangeAppLifecycleState(state);
    if (state == AppLifecycleState.resumed) {
      setState(() {});
    }
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text(widget.title)),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            const Text(
              'You have pushed the button this many times:',
            ),
            FutureBuilder<int>(
              future: _value,
              builder: (_, snapshot) => Text(
                (snapshot.data ?? 0).toString(),
                style: Theme.of(context).textTheme.headlineMedium,
              ),
            ),
            TextButton(
              onPressed: () async {
                await _clear();
                setState(() {});
              },
              child: const Text('Clear'),
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _incrementCounter,
        tooltip: 'Increment',
        child: const Icon(Icons.add),
      ),
    );
  }
}

iOS Widget

Note: As of writing this you will required XCode 15 for this

Like mentioned above I assume that you already know how to build HomeWidgets. If not please check out the README as well as have a look at the Codelab. Before adding interactivity you should have performed at least these steps:

1. Add an AppIdentifier and GroupIdentifier on the AppleDeveloper Console
2. Create a WidgetExtension in Xcode. File > New > Target > Widget Extension In this example I’ve named the extension CounterWidget
3. Add your GroupId to both your App Target and Widget Extension Target

Adjust your podfile

We need to adjust the Podfile for your iOS app to make sure your WidgetExtension has access to the home_widget plugin. For that we’ll add the following code snippet

target 'CounterWidgetExtension' do
  inherit! :search_paths
end

To your Runner’s target section in the Podfile so the whole section will look like this:

target 'Runner' do
  use_frameworks!
  use_modular_headers!

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
  target 'RunnerTests' do
    inherit! :search_paths
  end
  target 'CounterWidgetExtension' do
    inherit! :search_paths
  end
end

Creating an AppIntent

In your Runners target you want to create a new swift file where we will define an AppIntent which we will use to trigger Actions from the Widget. When creating the AppIntent it is important that you select both your Runner and your WidgetExtension as targets (you can also set this in the inspector later)

In the AppIntent’s perform function call HomeWidgetBackgroundWorker.run this needs to be called with your AppGroupId and an Uri which will be passed into the interactivity callback in dart

import AppIntents
import Foundation
import home_widget

@available(iOS 17, *)
public struct BackgroundIntent: AppIntent {
  static public var title: LocalizedStringResource = "Increment Counter"

  @Parameter(title: "Method")
  var method: String

  public init() {
    method = "increment"
  }

  public init(method: String) {
    self.method = method
  }

  public func perform() async throws -> some IntentResult {
    await HomeWidgetBackgroundWorker.run(
      url: URL(string: "homeWidgetCounter://\(method)"),
      appGroup: "YOUR_GROUP_ID")

    return .result()
  }
}

Adding the Button to the Widget

As a last step we will need to add a Button to our Widget that will use the BackgroundIntent we just created. So we are now back in our CounterWidget.swift and can simply add interactive buttons to the Widget like this

Button(intent: BackgroundIntent(method: "increment")) {
  Image(systemName: "plus").font(.system(size: 16))
}

The full CounterWidget.swift should look something like this. There you can also see how to load the current count into a TimelineEntry

import SwiftUI
import WidgetKit

struct Provider: TimelineProvider {
  func placeholder(in context: Context) -> CounterEntry {
    CounterEntry(date: Date(), count: 0)
  }

  func getSnapshot(in context: Context, completion: @escaping (CounterEntry) -> Void) {
    // Get the UserDefaults for the AppGroup
    let prefs = UserDefaults(suiteName: "YOUR_GROUP_ID")
    // Load the current Count
    let entry = CounterEntry(date: Date(), count: prefs?.integer(forKey: "counter") ?? 0)
    completion(entry)
  }

  func getTimeline(in context: Context, completion: @escaping (Timeline<Entry>) -> Void) {
    getSnapshot(in: context) { (entry) in
      let timeline = Timeline(entries: [entry], policy: .atEnd)
      completion(timeline)
    }
  }
}

struct CounterEntry: TimelineEntry {
  let date: Date
  let count: Int
}

struct CounterWidgetEntryView: View {
  var entry: Provider.Entry

  var body: some View {
    VStack {
      Text("You have pushed the button this many times:").font(.caption2).frame(
        maxWidth: .infinity, alignment: .center)
      Spacer()
      Text(entry.count.description).font(.title).frame(maxWidth: .infinity, alignment: .center)
      Spacer()
      HStack {
        // This button is for clearing
        Button(intent: BackgroundIntent(method: "clear")) {
          Image(systemName: "xmark").font(.system(size: 16)).foregroundColor(.red).frame(
            width: 24, height: 24)
        }.buttonStyle(.plain).frame(alignment: .leading)
        Spacer()
        // This button is for incrementing
        Button(intent: BackgroundIntent(method: "increment")) {
          Image(systemName: "plus").font(.system(size: 16)).foregroundColor(.white)

        }.frame(width: 24, height: 24)
          .background(.blue)
          .cornerRadius(12).frame(alignment: .trailing)
      }
    }
  }
}

struct CounterWidget: Widget {
  let kind: String = "CounterWidget"

  var body: some WidgetConfiguration {
    StaticConfiguration(kind: kind, provider: Provider()) { entry in
      if #available(iOS 17.0, *) {
        CounterWidgetEntryView(entry: entry)
          .containerBackground(.fill.tertiary, for: .widget)
      } else {
        CounterWidgetEntryView(entry: entry)
          .padding()
          .background()
      }
    }
    .configurationDisplayName("Counter Widget")
    .description("Count the Number Up")
  }
}

#Preview(as: .systemSmall){
  CounterWidget()
} timeline: {
  CounterEntry(date: .now, count: 0)
}

Now run the App and start counting right from the HomeScreen

Android Widget

Like mentioned above I assume that you already know how to build HomeWidgets. If not please check out the README as well as have a look at the Codelab. Before adding interactivity you should have performed at least these steps:

1. Create a WidgetProvider (In our case CounterWidgetProvider)
2. Create your WidgetLayout and xml appwidget-provider
3. Add your Widget to the AndroidManifest

Adding Interactivity

To add interactivity simply assign a `HomeWidgetBackgroundIntent` to your Remote View.

val incrementIntent = HomeWidgetBackgroundIntent.getBroadcast(
  context,
  Uri.parse("homeWidgetCounter://increment")
)
setOnClickPendingIntent(R.id.button_increment, incrementIntent)

The full CounterWidgetProvider.kt should look something like this

package es.antonborri.home_widget_counter

import android.appwidget.AppWidgetManager
import android.content.Context
import android.content.SharedPreferences
import android.net.Uri
import android.widget.RemoteViews
import es.antonborri.home_widget.HomeWidgetBackgroundIntent
import es.antonborri.home_widget.HomeWidgetProvider

class CounterWidgetProvider : HomeWidgetProvider() {
    override fun onUpdate(
            context: Context,
            appWidgetManager: AppWidgetManager,
            appWidgetIds: IntArray,
            widgetData: SharedPreferences) {
        appWidgetIds.forEach { widgetId ->
            val views = RemoteViews(context.packageName, R.layout.counter_widget).apply {
                val count = widgetData.getInt("counter", 0)
                setTextViewText(R.id.text_counter, count.toString())

                val incrementIntent = HomeWidgetBackgroundIntent.getBroadcast(
                        context,
                        Uri.parse("homeWidgetCounter://increment")
                )
                val clearIntent = HomeWidgetBackgroundIntent.getBroadcast(
                        context,
                        Uri.parse("homeWidgetCounter://clear")
                )

                setOnClickPendingIntent(R.id.button_increment, incrementIntent)
                setOnClickPendingIntent(R.id.button_clear, clearIntent)
            }
            appWidgetManager.updateAppWidget(widgetId, views)
        }
    }
}

And with that your interactive HomeScreenWidget is done. and should look like this.

Wrapping it up

Adding interactivity is not hard and can make your HomeScreenWidgets much more useful for your users.

The full code for the example app can be found here

GitHub - ABausG/home_widget_counter: An example App for home_widget rebuilding the Flutter Counter App as a HomeScreen Widget

Please check out and like home_widget on pub.dev

home_widget | Flutter package

Do you have an issue with home_widget please create an issue on github

GitHub - ABausG/home_widget: Flutter Package for Easier Creation of Home Screen Widgets

Building something cool with home_widget ? Let me know over on Twitter/X