Building iOS 18 Widgets & App Intents with Claude Code: A Complete Implementation Guide

import WidgetKit
import SwiftUI
 
// The data unit your widget displays at each point in time
struct TaskEntry: TimelineEntry {
    let date: Date
    let taskCount: Int
    let nextDeadline: Date?
    let completionRate: Double
    let highPriorityTitles: [String]
}
 
struct TaskTimelineProvider: TimelineProvider {
    typealias Entry = TaskEntry
 
    // Shown immediately while the real data loads — keep it fast
    func placeholder(in context: Context) -> TaskEntry {
        TaskEntry(
            date: Date(),
            taskCount: 3,
            nextDeadline: Calendar.current.date(byAdding: .hour, value: 2, to: Date()),
            completionRate: 0.6,
            highPriorityTitles: ["Write report", "Review PR"]
        )
    }
 
    // Used in the widget gallery — also needs to be fast
    // ⚠️ Slow snapshots make the gallery feel broken; reviewers see this too
    func getSnapshot(in context: Context, completion: @escaping (TaskEntry) -> Void) {
        let entry = TaskEntry(
            date: Date(),
            taskCount: 5,
            nextDeadline: Calendar.current.date(byAdding: .hour, value: 1, to: Date()),
            completionRate: 0.8,
            highPriorityTitles: ["Write report", "Review PR", "Ship release"]
        )
        completion(entry)
    }
 
    // The real timeline — called when system needs fresh data
    func getTimeline(in context: Context, completion: @escaping (Timeline<TaskEntry>) -> Void) {
        var entries: [TaskEntry] = []
        let now = Date()
 
        // ⚠️ UserDefaults.standard is NOT accessible from a widget extension
        // Always use App Group shared storage
        let sharedDefaults = UserDefaults(suiteName: "group.com.yourapp.shared")
        let taskCount = sharedDefaults?.integer(forKey: "taskCount") ?? 0
        let completionRate = sharedDefaults?.double(forKey: "completionRate") ?? 0.0
        let titles = sharedDefaults?.stringArray(forKey: "highPriorityTitles") ?? []
 
        // Generate 15-minute interval entries for the next hour
        for minuteOffset in stride(from: 0, to: 60, by: 15) {
            guard let entryDate = Calendar.current.date(
                byAdding: .minute, value: minuteOffset, to: now
            ) else { continue }
 
            entries.append(TaskEntry(
                date: entryDate,
                taskCount: taskCount,
                nextDeadline: sharedDefaults?.object(forKey: "nextDeadline") as? Date,
                completionRate: completionRate,
                highPriorityTitles: titles
            ))
        }
 
        // Timeline refresh policies:
        // .atEnd     — system calls getTimeline again after the last entry (default choice)
        // .after(date) — refresh at a specific future time (good for deadline-driven content)
        // .never     — only refresh when you call WidgetCenter.shared.reloadTimelines manually
        let timeline = Timeline(entries: entries, policy: .atEnd)
        completion(timeline)
    }
}

import AppIntents
import WidgetKit
 
// The intent that runs when the user taps the widget button
struct CompleteTaskIntent: AppIntent {
    static var title: LocalizedStringResource = "Complete Task"
    static var description = IntentDescription("Marks a task as done from the widget")
 
    @Parameter(title: "Task ID")
    var taskId: String
 
    func perform() async throws -> some IntentResult {
        let sharedDefaults = UserDefaults(suiteName: "group.com.yourapp.shared")
        var completedIds = sharedDefaults?.stringArray(forKey: "completedTaskIds") ?? []
 
        guard \!completedIds.contains(taskId) else {
            return .result() // Already completed — idempotent
        }
 
        completedIds.append(taskId)
        sharedDefaults?.set(completedIds, forKey: "completedTaskIds")
 
        // Trigger a timeline reload so the widget reflects the new state
        // ⚠️ This schedules a reload — the widget won't update synchronously mid-render
        WidgetCenter.shared.reloadTimelines(ofKind: "TaskWidget")
 
        return .result()
    }
}
 
// Widget view with interactive controls
struct TaskWidgetView: View {
    let entry: TaskEntry
 
    var body: some View {
        VStack(alignment: .leading, spacing: 8) {
            HStack {
                Text("Today's Tasks")
                    .font(.caption)
                    .foregroundStyle(.secondary)
                Spacer()
                Text("\(entry.taskCount)")
                    .font(.title2.bold())
            }
 
            ProgressView(value: entry.completionRate)
                .tint(entry.completionRate >= 0.8 ? .green : .orange)
 
            if let title = entry.highPriorityTitles.first {
                HStack {
                    Text(title)
                        .font(.caption2)
                        .lineLimit(1)
                    Spacer()
                    // Interactive button — links to AppIntent, not a closure
                    Button(intent: CompleteTaskIntent(taskId: "top-priority")) {
                        Image(systemName: "checkmark.circle")
                            .foregroundStyle(.green)
                    }
                    .buttonStyle(.plain)
                }
            }
        }
        .padding()
        // ⚠️ This modifier is required in iOS 17+ for interactive widgets to work
        // Missing it can silently disable button interactions
        .containerBackground(.fill.tertiary, for: .widget)
    }
}

import ActivityKit
import SwiftUI
 
struct BuildTaskAttributes: ActivityAttributes {
    // ContentState: changes during the activity life cycle
    public struct ContentState: Codable, Hashable {
        var progress: Double        // 0.0 to 1.0
        var currentStep: String
        var elapsedSeconds: Int
        var isComplete: Bool
        var errorMessage: String?   // nil when everything is fine
    }
 
    // Static data: fixed at the time Activity.request is called
    let taskName: String
    let startedAt: Date
    let estimatedDurationSeconds: Int
}
 
// Starting a Live Activity
func startBuildActivity(taskName: String, estimatedDuration: Int) -> Activity<BuildTaskAttributes>? {
    // Check authorization — user can disable Live Activities in Settings
    guard ActivityAuthorizationInfo().areActivitiesEnabled else {
        print("Live Activities are disabled. Ask user to enable in Settings → Notifications → Live Activities.")
        return nil
    }
 
    let attributes = BuildTaskAttributes(
        taskName: taskName,
        startedAt: Date(),
        estimatedDurationSeconds: estimatedDuration
    )
 
    let initialState = BuildTaskAttributes.ContentState(
        progress: 0.0,
        currentStep: "Initializing",
        elapsedSeconds: 0,
        isComplete: false,
        errorMessage: nil
    )
 
    // staleDate: past this time, the system may visually indicate stale data
    let content = ActivityContent(
        state: initialState,
        staleDate: Calendar.current.date(byAdding: .minute, value: 30, to: Date())
    )
 
    do {
        // pushType: .token enables remote updates via APNs (useful for server-driven activities)
        // pushType: nil for purely local updates
        let activity = try Activity.request(
            attributes: attributes,
            content: content,
            pushType: .token
        )
        print("Live Activity started with ID: \(activity.id)")
        return activity
    } catch {
        // ActivityKitError code 4 is one of the most common:
        // usually NSSupportsLiveActivities missing or wrong target
        print("Failed to start Live Activity: \(error)")
        return nil
    }
}
 
// Updating a running Live Activity
func updateBuildActivity(
    _ activity: Activity<BuildTaskAttributes>,
    step: String,
    progress: Double,
    error: String? = nil
) async {
    let elapsed = Int(Date().timeIntervalSince(activity.attributes.startedAt))
    let updatedState = BuildTaskAttributes.ContentState(
        progress: min(progress, 1.0),
        currentStep: step,
        elapsedSeconds: elapsed,
        isComplete: progress >= 1.0,
        errorMessage: error
    )
 
    await activity.update(
        ActivityContent(
            state: updatedState,
            staleDate: Calendar.current.date(byAdding: .minute, value: 5, to: Date())
        )
    )
}
 
// Ending a Live Activity
func endBuildActivity(_ activity: Activity<BuildTaskAttributes>, success: Bool) async {
    let finalState = BuildTaskAttributes.ContentState(
        progress: 1.0,
        currentStep: success ? "Complete" : "Failed",
        elapsedSeconds: Int(Date().timeIntervalSince(activity.attributes.startedAt)),
        isComplete: true,
        errorMessage: success ? nil : "Build failed — check Xcode logs"
    )
 
    // .immediate: dismiss the Live Activity right away
    // .default: keep it visible for a few seconds after ending
    // .after(date): keep it visible until a specific time (good for results users want to read)
    await activity.end(
        ActivityContent(state: finalState, staleDate: nil),
        dismissalPolicy: .after(Date().addingTimeInterval(30))
    )
}

import ActivityKit
import SwiftUI
import WidgetKit
 
struct BuildActivityWidget: Widget {
    var body: some WidgetConfiguration {
        ActivityConfiguration(for: BuildTaskAttributes.self) { context in
            // Lock screen / StandBy view
            LockScreenLiveActivityView(context: context)
        } dynamicIsland: { context in
            DynamicIsland {
                // Expanded view (user long-presses)
                DynamicIslandExpandedRegion(.leading) {
                    Label(context.attributes.taskName, systemImage: "hammer.fill")
                        .font(.caption)
                        .lineLimit(1)
                }
                DynamicIslandExpandedRegion(.trailing) {
                    Text(String(format: "%.0f%%", context.state.progress * 100))
                        .font(.caption.monospacedDigit())
                        .foregroundStyle(context.state.isComplete ? .green : .primary)
                }
                DynamicIslandExpandedRegion(.bottom) {
                    VStack(spacing: 4) {
                        ProgressView(value: context.state.progress)
                            .tint(context.state.errorMessage \!= nil ? .red : .orange)
                        if let error = context.state.errorMessage {
                            Text(error)
                                .font(.caption2)
                                .foregroundStyle(.red)
                        } else {
                            Text(context.state.currentStep)
                                .font(.caption2)
                                .foregroundStyle(.secondary)
                        }
                    }
                }
            } compactLeading: {
                // Compact left — shown when another app uses the island
                Image(systemName: context.state.isComplete ? "checkmark.circle.fill" : "hammer.fill")
                    .foregroundStyle(context.state.isComplete ? .green : .orange)
            } compactTrailing: {
                // Compact right
                Text(String(format: "%.0f%%", context.state.progress * 100))
                    .font(.caption2.monospacedDigit())
            } minimal: {
                // Minimal — shown when two activities compete for the island
                ProgressView(value: context.state.progress)
                    .progressViewStyle(.circular)
                    .tint(context.state.isComplete ? .green : .orange)
            }
        }
    }
}
 
struct LockScreenLiveActivityView: View {
    let context: ActivityViewContext<BuildTaskAttributes>
 
    var body: some View {
        HStack {
            VStack(alignment: .leading) {
                Text(context.attributes.taskName)
                    .font(.headline)
                    .lineLimit(1)
                Text(context.state.currentStep)
                    .font(.caption)
                    .foregroundStyle(.secondary)
            }
            Spacer()
            VStack(alignment: .trailing) {
                Text(String(format: "%.0f%%", context.state.progress * 100))
                    .font(.title3.bold().monospacedDigit())
                Text("\(context.state.elapsedSeconds / 60)m elapsed")
                    .font(.caption2)
                    .foregroundStyle(.tertiary)
            }
        }
        .padding()
        .activityBackgroundTint(.black.opacity(0.6))
    }
}