Adding a Wallpaper Shuffle to the iOS 18 Control Center in a Rork App

The AppIntent — what the button actually does

The AppIntent is the real body of the control. It opens the App Group UserDefaults and advances the current index by one.

import AppIntents
import WidgetKit
 
struct ShuffleWallpaperIntent: AppIntent {
    static var title: LocalizedStringResource = "Shuffle Wallpaper"
    static var description = IntentDescription("Pick the next wallpaper")
 
    // Runs straight from Control Center, so no app launch
    static var openAppWhenRun: Bool = false
 
    func perform() async throws -> some IntentResult {
        let group = "group.design.dolice.wallpaper"
        guard let store = UserDefaults(suiteName: group) else {
            return .result()
        }
        let total = max(store.integer(forKey: "wallpaperCount"), 1)
        let current = store.integer(forKey: "wallpaperIndex")
        let next = (current + 1) % total
 
        store.set(next, forKey: "wallpaperIndex")
        store.set(Date().timeIntervalSince1970, forKey: "lastShuffledAt")
 
        // Needed when the control's appearance (a number, etc.) should update
        ControlCenter.shared.reloadControls(
            ofKind: "design.dolice.wallpaper.shuffle"
        )
        return .result()
    }
}

The key line is openAppWhenRun = false. Set it to true and the app jumps to the foreground every time — exactly the opposite of "change it without opening." For a wallpaper control, false is the right default.

The ControlWidget — the part that sits in Control Center

Next, define the button that shows up in Control Center. It just binds the AppIntent above to a ControlWidgetButton.

import WidgetKit
import SwiftUI
import AppIntents
 
struct WallpaperShuffleControl: ControlWidget {
    var body: some ControlWidgetConfiguration {
        StaticControlConfiguration(
            kind: "design.dolice.wallpaper.shuffle"
        ) {
            ControlWidgetButton(action: ShuffleWallpaperIntent()) {
                Label("Shuffle", systemImage: "shuffle")
            }
        }
        .displayName("Wallpaper Shuffle")
        .description("Pick the next wallpaper from Control Center")
    }
}
 
@main
struct WallpaperControlBundle: ControlWidgetBundle {
    var body: some ControlWidget {
        WallpaperShuffleControl()
    }
}

The kind string must match the reloadControls(ofKind:) call inside the AppIntent. If it drifts, the button renders but reloadControls misses and the displayed state never updates. I first hardcoded this string in two files, fixed only one, and lost the better part of an hour. Define kind once as a constant and reference it from both sides.

Wiring it to Rork (Expo) — don't let prebuild erase it

This is where React Native (Rork / Expo) projects hurt the most. Every expo prebuild regenerates the ios/ directory, so any extension target or App Group you set up by hand in Xcode is wiped each time. Fixing it by hand forever is not realistic.

At first I naively added the target directly in Xcode.

// Before (manual; erased by prebuild)
1. Xcode: File > New > Target > Widget Extension
2. Signing & Capabilities: add the App Group by hand
3. Run prebuild; ios/ regenerates and steps 1-2 vanish
4. Repeat the same chore every release

Move it into a config plugin and the setup survives regeneration.

// After (declared in app.config.js; reproduced by prebuild)
const { withEntitlementsPlist } = require("expo/config-plugins");
 
const withWallpaperAppGroup = (config) => {
  return withEntitlementsPlist(config, (cfg) => {
    cfg.modResults["com.apple.security.application-groups"] = [
      "group.design.dolice.wallpaper",
    ];
    return cfg;
  });
};
 
module.exports = {
  name: "wallpaper",
  ios: { bundleIdentifier: "design.dolice.wallpaper" },
  plugins: [withWallpaperAppGroup],
};

Adding the extension target itself is best handed to a plugin like @bacons/apple-targets, which carries the .swift files and the App Group through prebuild together. I run about six wallpaper apps in parallel as an indie developer, and since I moved this configuration into code, the grind of hand-patching every app on each OS update dropped sharply.

From the JS side, write the wallpaper count into the shared store. A thin native bridge that calls UserDefaults(suiteName:) is enough; call it on launch and whenever the library updates.

// Share the total right after loading the wallpaper library
import { NativeModules } from "react-native";
 
const { WallpaperBridge } = NativeModules;
 
export async function syncWallpaperCount(count) {
  // Write the total into the App Group UserDefaults
  await WallpaperBridge.setSharedInt("wallpaperCount", count);
}

What tripped me up — three causes of "tap does nothing"

On device, the button appeared but tapping it did nothing several times. The causes converged on three things.

First, a mismatched App Group identifier. If group.design.dolice.wallpaper differs by even one character between the main app and the extension entitlements, UserDefaults(suiteName:) returns nil and nothing is written. Generate both from the same constant.

Second, forgetting reloadControls(ofKind:). The value can be written correctly inside the AppIntent, but if the control's display never refreshes it merely looks dead. If you surface a number or state in the label, call ControlCenter.shared.reloadControls right after the write.

Third, simulator quirks. Custom Control Center controls behave inconsistently in the simulator; in my setup only a real device verified correctly. The Crashlytics reports that matter come from devices anyway, so switching to on-device testing early was the shortcut. Keep one physical device on hand from the start so you don't burn time during testing.

What I think after shipping it

I ran it on a single wallpaper app for about two weeks. Not many users actually added the control — customizing Control Center is still an unfamiliar gesture for most people. But the ones who did add it open the app noticeably more often, so it seems to help retention among the core audience.

On cost/benefit: it is not worth front-loading on a brand-new app. But if your app already ships a home-screen widget, the WidgetKit foundation is reusable and the marginal cost is small, so it is worth adding. My rule became "add it to apps that already have widgets; for apps that don't, get the widget right first."

One practical review note: App Store review checks that the control does what its description says. A control labeled "shuffle" that merely opens the app invites a rejection, so decide the openAppWhenRun behavior up front.

If you want to try it next, take an app that already supports widgets, extract the kind string into a constant, and wire one AppIntent to one ControlWidget in the smallest possible form. Once you can tell "displayed" apart from "unresponsive," the same shape applies cleanly to one-tap features beyond wallpapers.