Putting a Wallpaper Shuffle in Control Center — a ControlWidget in a Rork (Expo) App, Rebuilt for iOS 26

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 {
        guard let store = UserDefaults(
            suiteName: WallpaperControlKind.appGroup
        ) 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: WallpaperControlKind.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: WallpaperControlKind.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. WallpaperControlKind above exists because of that afternoon.

Stateful controls need a Toggle and a ControlValueProvider

This is the section that grew the most during the rebuild. Alongside the "advance one image per tap" button, I wanted an on/off setting for automatic daily shuffling. Anything with real state belongs in a toggle, not a button.

A toggle is three parts: a ControlValueProvider that reports the current value, a SetValueIntent that writes it, and a ControlWidgetToggle that binds them together.

import AppIntents
import SwiftUI
import WidgetKit
 
struct DailyShuffleValueProvider: ControlValueProvider {
    // Shown in the controls gallery and Action button settings
    let previewValue = true
 
    func currentValue() async throws -> Bool {
        let store = UserDefaults(suiteName: WallpaperControlKind.appGroup)
        return store?.bool(forKey: "dailyShuffleEnabled") ?? false
    }
}
 
struct SetDailyShuffleIntent: SetValueIntent {
    static var title: LocalizedStringResource = "Toggle Daily Shuffle"
 
    // SetValueIntent requires a @Parameter literally named value
    @Parameter(title: "On") var value: Bool
 
    func perform() async throws -> some IntentResult {
        UserDefaults(suiteName: WallpaperControlKind.appGroup)?
            .set(value, forKey: "dailyShuffleEnabled")
        return .result()
    }
}
 
struct DailyShuffleControl: ControlWidget {
    var body: some ControlWidgetConfiguration {
        StaticControlConfiguration(
            kind: WallpaperControlKind.dailyShuffle,
            provider: DailyShuffleValueProvider()
        ) { isOn in
            ControlWidgetToggle(
                "Daily Shuffle",
                isOn: isOn,
                action: SetDailyShuffleIntent()
            ) { isOn in
                Label(
                    isOn ? "On" : "Off",
                    systemImage: isOn ? "shuffle.circle.fill" : "shuffle.circle"
                )
            }
        }
    }
}

Do not treat previewValue as a throwaway. It is the first thing a user sees in the gallery. currentValue() resolves asynchronously, so at the moment the gallery opens the real value has not arrived yet and previewValue is the control's first impression. I originally set mine to false, which meant the gallery showed a row of dimmed off-state icons that told nobody what the control was for.

Choosing between the shapes:

When in doubt, start with the button. The moment a control holds state, you inherit the whole synchronization question: when currentValue() gets called, and where you fire reloadControls.

What iOS 26 changed — design for a single color

iOS 26 moved the system to Liquid Glass, and widget and control rendering moved with it. Backgrounds are replaced by the system's glass material, and content is tinted through accented rendering mode.

The practical consequence is blunt: multicolor symbols and carefully composed full-color artwork will not render the way you intended. Wallpaper apps are especially tempted to show a thumbnail, so how quickly you accept this determines how much rework you do. I moved control labels to a single-color SF Symbol plus a short string, and left the artwork itself to the app and the home-screen widget.

If you ship a home-screen widget alongside the control, you can branch on the rendering mode.

struct WallpaperWidgetView: View {
    @Environment(\.widgetRenderingMode) private var renderingMode
    let image: Image
 
    var body: some View {
        switch renderingMode {
        case .accented:
            // Color is overridden by the system, so communicate with shape
            Label("Today's pick", systemImage: "photo.on.rectangle.angled")
        default:
            image.resizable().scaledToFill()
        }
    }
}

The other shift worth designing around is how many surfaces now mount the same AppIntent: Control Center, the Lock Screen, the Action button, and Control Center on watchOS 26. Rather than writing a separate implementation per entry point, build one AppIntent correctly and reference it from every surface. Then the next OS that adds a surface costs you almost nothing. That framing was the real payoff of the rebuild.

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. The same applies to toggles: change the setting from inside the app without that call, and Control Center keeps showing the stale state.

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.

Handing off the last step

As noted, the control cannot set the wallpaper. So the quality of the experience comes down to how you guide the user from "next image decided" to "wallpaper actually set." What I settled on: write the confirmed index into the App Group, and when the user next opens the app, preview that image and quietly surface a path to save it through the share sheet.

Automating all the way through a Shortcut is technically possible, but the permission dialog it introduces raised first-run drop-off in my testing. Wallpaper users arrive looking for something easy, so keeping the first experience at "tap the button, and next time you open the app today's pick is waiting" retained better. You can ratchet up the automation later, once you have a core audience.

Write more than the index into the App Group — storing the timestamp (lastShuffledAt) too makes it easy to add "suggest a fresh pick if more than 24 hours have passed." A small touch, but it quietly helped build a daily habit.

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." With iOS 26 multiplying the surfaces a single AppIntent can reach, that math tilts further in favor of adding it.

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.