<!--
{
  "availability" : [
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "WatchKit",
  "identifier" : "/documentation/WatchKit/WKInterfaceTimer",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "WatchKit"
    ],
    "preciseIdentifier" : "c:objc(cs)WKInterfaceTimer"
  },
  "title" : "WKInterfaceTimer"
}
-->

# WKInterfaceTimer

A label that displays a countdown or count-up timer.

```
class WKInterfaceTimer
```

## Overview

Use a timer object to configure the amount of time and the appearance of the timer text. When you start the timer, WatchKit updates the displayed text automatically on the user’s Apple Watch without further interactions from your extension. To know when the timer reaches 0, configure a <doc://com.apple.documentation/documentation/Foundation/Timer> object with the same target date you used to set up the timer.

Do not subclass or create instances of this class yourself. Instead, define outlets in your interface controller class and connect them to the corresponding objects in your storyboard file. For example, to refer to a timer object in your interface, define a property with the following syntax in your interface controller class:

```objc
@property (weak, nonatomic) IBOutlet WKInterfaceTimer* myTimer;
```

During the initialization of your interface controller, WatchKit creates any needed timer objects and assigns them to their connected outlets. At that point, you can use those objects to reconfigure the corresponding timers.

> Important:
> This class provides methods for configuring interface objects at initialization time or while an interface controller is active on the user’s Apple Watch. WatchKit coalesces the data from all setter method calls made during the same run loop iteration and transmits it to the device at the end of the run loop. If you set an attribute to different values in the same run loop iteration,  only the last value is transmitted. If you set an attribute to the same value in the same run loop iteration, WatchKit generates a log message so that you can track down the duplicate change.

### Interface Builder Configuration Options

Xcode lets you configure information about your timer interface object in your storyboard file. The following table lists the attributes you can configure and their meaning.

|Attribute   |Description                                                                                                                                                                                                                                                                                             |
|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|Format      |The format of the timer string. Select different options to update the appearance of the timer label in your storyboard scene.                                                                                                                                                                          |
|Enabled     |A checkbox indicating whether the timer starts running as soon as your interface is initialized.                                                                                                                                                                                                        |
|Units       |The units to be displayed in the label. Enabling checkboxes in this section causes the timer to display the corresponding units that are in range of the time. In other words, a timer with 2 minutes remaining displays minutes and seconds only; it does not display hours, days, or any larger units.|
|Preview Secs|The initial number of seconds for the timer. You can change this value programmatically using the ``doc://com.apple.watchkit/documentation/WatchKit/WKInterfaceTimer/setDate(_:)`` method.                                                                                                              |

A date object is a custom label whose text you cannot set directly. However, you can customize the appearance of the date object as you would for a label using the Attributes inspector in Xcode. For information about the label attributes you can configure, see [`WKInterfaceLabel`](/documentation/WatchKit/WKInterfaceLabel).

## Topics

### Configuring the Timer Attributes

[`-  setDate:`](/documentation/WatchKit/WKInterfaceTimer/setDate(_:))

Changes the start time for the timer.

[`-  setTextColor:`](/documentation/WatchKit/WKInterfaceTimer/setTextColor(_:))

Sets the color of the timer’s text.

### Starting and Stopping the Timer

[`-  start`](/documentation/WatchKit/WKInterfaceTimer/start())

Begins updates to the timer’s display.

[`-  stop`](/documentation/WatchKit/WKInterfaceTimer/stop())

Stops updates to the timer’s display.

## Relationships

### Conforms To

[`CVarArg`](/documentation/Swift/CVarArg)

[`Hashable`](/documentation/Swift/Hashable)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`Equatable`](/documentation/Swift/Equatable)

### Inherits From

[`WKInterfaceObject`](/documentation/WatchKit/WKInterfaceObject)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)