WatchKit — what it is, the Apple Watch framework and watchOS

What is WatchKit and How Does It Work?

WatchKit is an Apple framework that provides an API for creating applications on Apple Watch. Starting with watchOS 2 (2015), WatchKit apps run directly on the watch rather than on the iPhone, allowing them to process data and display the interface without a constant connection to the phone. Before that, in watchOS 1, all apps ran on the iPhone and the watch was merely a remote display, causing significant UI delays.

The modern WatchKit architecture includes two components: WatchKit App (Storyboard + resources on the watch) and WatchKit Extension (code running on the watch). The user installs both components through the App Store when installing the parent iOS application. WatchKit integrates with system features: notifications (via UNUserNotificationCenter), complications (data on the watch face), Workout API, and HealthKit.

According to Counterpoint Research (2025), Apple Watch holds 52% of the global smartwatch market, and the average user installs 6–8 third-party apps using WatchKit or SwiftUI. The most popular categories are fitness (56%), health (22%), navigation (9%), and utilities (8%).

WatchKit vs SwiftUI for watchOS

SwiftUI is Apple’s recommended way to build interfaces for watchOS starting with watchOS 6. SwiftUI provides declarative syntax and automatic adaptation to screen sizes. However, WatchKit remains relevant for projects started before SwiftUI existed, for using specific elements (WKInterfaceMap, WKInterfaceMovie), and in cases where support for watchOS versions below 6 is required.

WatchKit Interface: WKInterfaceController and Elements

WKInterfaceController is the base class for managing screens in WatchKit. It handles the lifecycle: initialization (awake(withContext:)), appearance (willActivate), disappearance (didDeactivate), and context transfer between controllers. Each app screen is represented by a separate WKInterfaceController subclass connected to the Storyboard via Interface Builder. Navigation can be hierarchical (push) or modal (present).

WatchKit provides a set of interface elements with the WKInterface prefix: WKInterfaceLabel (text), WKInterfaceButton (button), WKInterfaceTable (table), WKInterfaceImage (image), WKInterfaceMap (map), and WKInterfaceGroup (container with rounding and background). All elements work asynchronously — UI changes are queued and applied by the system between render cycles, ensuring stable 30 FPS on the watch screen.

Basic WKInterfaceController

class MainInterfaceController: WKInterfaceController {
    @IBOutlet weak var titleLabel: WKInterfaceLabel!
    @IBOutlet weak var actionButton: WKInterfaceButton!
    
    override func awake(with context: Any?) {
        super.awake(with: context)
        titleLabel.setText("Hello, Watch!")
    }
    
    override func willActivate() {
        super.willActivate()
        actionButton.setTitle("Start")
    }
    
    @IBAction func didTapButton() {
        pushController(withName: "DetailController", context: nil)
    }
}

WCSession: Communication Between Watch and iPhone

WCSession is the central class for two-way communication between Apple Watch and iPhone via Bluetooth or Wi-Fi. The session allows transferring small data dictionaries (updateApplicationContext), sending messages with immediate response (sendMessage), transferring files (transferFile), and synchronizing complex objects (transferUserInfo). WCSession works asynchronously and automatically selects the optimal communication channel.

To use WCSession, you must activate the session on both devices. The Watch app creates a WCSession in the willActivate() method, while the iOS app does so in AppDelegate or SceneDelegate. Once activated, the devices automatically synchronize context when possible. It is important to handle the WCSessionDelegate for receiving incoming data and monitoring connection status.

WCSession Example on the Watch Side

class SessionManager: NSObject, WCSessionDelegate {
    private let session = WCSession.default
    
    func activate() {
        session.delegate = self
        session.activate()
    }
    
    func sendDataToPhone(key: String, value: Any) {
        guard session.isReachable else { return }
        session.sendMessage([key: value],
            replyHandler: { response in
                print("Response: \(response)")
            },
            errorHandler: { error in
                print("Error: \(error.localizedDescription)")
            }
        )
    }
    
    func session(_ session: WCSession,
               didReceiveMessage message: [String: Any],
               replyHandler: @escaping ([String: Any]) -> Void) {
        handleIncomingData(message)
        replyHandler(["status": "ok"])
    }
}

Complications: Data on the Watch Face

Complications are small data elements displayed on the Apple Watch face that provide quick access to information without opening the app. WatchKit provides CLKComplicationDataSource — a protocol whose implementation allows the app to supply data for complications. The watch face itself decides which positions are available — circular, rectangular, corner, or modular.

Developers can provide complications for three size families: CLKComplicationFamily — circularSmall, extraLarge, graphicCircular, graphicRectangular, graphicCorner, graphicBezel, modularSmall, modularLarge, and utilitarianSmall/Large. Each family has its own dimensions and display format. An app can support multiple families, but a minimum of two — graphic and modular — is recommended.

CLKComplicationDataSource Example

class ComplicationController: NSObject, CLKComplicationDataSource {
    func getCurrentTimelineEntry(
        for complication: CLKComplication,
        withHandler handler: @escaping (CLKComplicationTimelineEntry?) -> Void
    ) {
        let template = CLKComplicationTemplateModularSmallSimpleText()
        template.textProvider = CLKSimpleTextProvider(text: "96%")
        let entry = CLKComplicationTimelineEntry(
            date: Date(),
            complicationTemplate: template
        )
        handler(entry)
    }
}

Sample WatchKit App in Swift

Creating a WatchKit app begins by adding a WatchKit App Target in Xcode. Xcode generates an Interface.storyboard with an initial controller and automatically links it to the InterfaceController class. The developer adds UI elements through Interface Builder and creates IBOutlets for code interaction. Below is a complete controller example with a table of data received from iPhone via WCSession.

class ItemRowController: NSObject {
    @IBOutlet weak var itemLabel: WKInterfaceLabel!
    
    func configure(with text: String) {
        itemLabel.setText(text)
    }
}

class ListController: WKInterfaceController {
    @IBOutlet weak var itemsTable: WKInterfaceTable!
    private var items: [String] = []
    
    override func awake(with context: Any?) {
        super.awake(with: context)
        items = context as? [String] ?? []
        
        itemsTable.setNumberOfRows(items.count,
            withRowType: "ItemRow")
        for i in 0..if let row = itemsTable
                .rowController(at: i) as? ItemRowController {
                row.configure(with: items[i])
            }
        }
    }
}

Workout API for Fitness Applications

Workout API is a set of WatchKit classes for creating fitness apps that can run workouts on Apple Watch in the background. The API provides access to sensors: accelerometer, gyroscope, heart rate monitor (via HKHealthStore), and GPS (on Watch models with GPS). Workouts are started via HKWorkoutSession from HealthKit, and heart rate data is updated in real time through HKSampleQuery.

The key advantage of the Workout API is background operation. When a workout is active, watchOS does not suspend the app when the user lowers their wrist — sensors continue collecting data, and the app can display heart rate, distance, pace, and other metrics. After the workout ends, data syncs with the Health app on iPhone via HealthKit, providing a unified fitness profile for the user.

Starting a Workout with Sensors

class WorkoutManager: NSObject {
    private let healthStore = HKHealthStore()
    private var session: HKWorkoutSession!
    
    func startWorkout(activityType: HKWorkoutActivityType) {
        let config = HKWorkoutConfiguration()
        config.activityType = activityType
        config.locationType = .outdoor
        
        session = try! HKWorkoutSession(
            healthStore: healthStore,
            configuration: config
        )
        session.startActivity(with: Date())
    }
    
    func stopWorkout() {
        session.stopActivity(with: Date())
        session.end()
    }
}