<!--
{
  "availability" : [
    "iOS: 3.1.0 -",
    "iPadOS: 3.1.0 -",
    "macCatalyst: 13.1.0 -",
    "macOS: 14.0.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "QuartzCore",
  "identifier" : "/documentation/QuartzCore/CADisplayLink",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Core Animation"
    ],
    "preciseIdentifier" : "c:objc(cs)CADisplayLink"
  },
  "title" : "CADisplayLink"
}
-->

# CADisplayLink

A timer object that allows your app to synchronize its drawing to the refresh rate of the display.

```
class CADisplayLink
```

## Overview

Your app initializes a new display link by providing a target object and a selector to call when the system updates the screen. To synchronize your display loop with the display, your application adds it to a run loop using the [`add(to:forMode:)`](/documentation/QuartzCore/CADisplayLink/add(to:forMode:)) method.

Once you associate the display link with a run loop, the system calls the selector on the target when the screen’s contents need to update. The target can read the display link’s [`timestamp`](/documentation/QuartzCore/CADisplayLink/timestamp) property to retrieve the time the system displayed the previous frame. For example, an app that displays movies might use `timestamp` to calculate which video frame to display next. An app that performs its own animations might use `timestamp` to determine where and how visible objects appear in the upcoming frame.

The [`duration`](/documentation/QuartzCore/CADisplayLink/duration) property provides the amount of time between frames at the <doc://com.apple.documentation/documentation/UIKit/UIScreen/maximumFramesPerSecond>. To calculate the actual frame duration, use [`targetTimestamp`](/documentation/QuartzCore/CADisplayLink/targetTimestamp) - [`timestamp`](/documentation/QuartzCore/CADisplayLink/timestamp). You can use this value in your app to calculate the frame rate of the display, the approximate time the system displays the next frame, and to adjust the drawing behavior so that the next frame is ready in time to display.

Your app can disable notifications by setting [`isPaused`](/documentation/QuartzCore/CADisplayLink/isPaused) to `true`. Also, if your app can’t provide frames in the time the system provides, you may want to choose a slower frame rate. An app with a slower but consistent frame rate appears smoother to the user than an app that skips frames. You can define the number of frames per second by setting [`preferredFramesPerSecond`](/documentation/QuartzCore/CADisplayLink/preferredFramesPerSecond).

When your app finishes with a display link, call [`invalidate()`](/documentation/QuartzCore/CADisplayLink/invalidate()) to remove it from all run loops and to disassociate it from the target.

The code listing below shows how to create a display link and add it to the current run loop. The display link invokes the step function, which prints the target timestamp with each screen update.

```swift
func createDisplayLink() {
    let displaylink = CADisplayLink(target: self,
                                    selector: #selector(step))
    
    displaylink.add(to: .current,
                    forMode: .defaultRunLoopMode)
}
     
func step(displaylink: CADisplayLink) {
    print(displaylink.targetTimestamp)
}
```

You shouldn’t subclass [`CADisplayLink`](/documentation/QuartzCore/CADisplayLink).

### Preferred and Actual Frame Rates

You control a display link’s frame rate (the number of times the system calls the selector of its target, per second) by setting [`preferredFramesPerSecond`](/documentation/QuartzCore/CADisplayLink/preferredFramesPerSecond). However, the actual frames per second may differ from the preferred value you set; actual frame rates are always a factor of the maximum refresh rate of the device. For example, if your device’s maximum refresh rate is 60 frames per second (defined by <doc://com.apple.documentation/documentation/UIKit/UIScreen/maximumFramesPerSecond>), actual frame rates include 15, 20, 30, and 60 frames per second. If you set a display link’s preferred frame rate to a value higher than the maximum, the actual frame rate is the maximum.

In iOS 15, frame rate availability can change due to the system factoring in the system policy and user preference — including Low Power Mode, critical thermal state, and accessibility settings.

The system rounds, to the nearest factor, preferred frame rates that aren’t a divisor of the maximum frame rate. For example, setting a preferred frame rate to either 26 or 35 frames per second on a device with a maximum refresh rate of 60 frames per second yields an actual frame rate of 30 times per second.

The code listing below shows how to calculate the actual frame rate by dividing 1 by your display link’s [`timestamp`](/documentation/QuartzCore/CADisplayLink/timestamp) subtracted from its [`targetTimestamp`](/documentation/QuartzCore/CADisplayLink/targetTimestamp).

```swift
// Calculate the actual frame rate.
let actualFramesPerSecond = 1 / (displaylink.targetTimestamp - displaylink.timestamp)
```

> Note:
> If your app needs more control over refresh rate to ensure smooth rendering of frames, use ``doc://com.apple.quartzcore/documentation/QuartzCore/CAMetalDisplayLink`` and the information from ``doc://com.apple.quartzcore/documentation/QuartzCore/CAMetalLayer`` instances to render frames.

## Topics

### Creating a Display Link

[`init(target:selector:)`](/documentation/QuartzCore/CADisplayLink/init(target:selector:))

Creates a display link for a target that calls its selector.

### Configuring a Display Link

[`duration`](/documentation/QuartzCore/CADisplayLink/duration)

The time interval between screen refresh updates.

[`preferredFrameRateRange`](/documentation/QuartzCore/CADisplayLink/preferredFrameRateRange)

A range of frequencies your app allows for frame updates, affecting how often the system invokes your delegate’s callback.

[`preferredFramesPerSecond`](/documentation/QuartzCore/CADisplayLink/preferredFramesPerSecond)

A frequency your app prefers for frame updates, affecting how often the system invokes your delegate’s callback.

[`isPaused`](/documentation/QuartzCore/CADisplayLink/isPaused)

A Boolean value that indicates whether the system suspends the display link’s notifications to the target.

[`timestamp`](/documentation/QuartzCore/CADisplayLink/timestamp)

The time interval that represents when the last frame displayed.

[`targetTimestamp`](/documentation/QuartzCore/CADisplayLink/targetTimestamp)

The time interval that represents when the next frame displays.

[`frameInterval`](/documentation/QuartzCore/CADisplayLink/frameInterval)

The number of frames that must pass before the display link notifies the target again.

### Scheduling a Display Link to Send Notifications

[`add(to:forMode:)`](/documentation/QuartzCore/CADisplayLink/add(to:forMode:))

Registers the display link with a run loop.

[`remove(from:forMode:)`](/documentation/QuartzCore/CADisplayLink/remove(from:forMode:))

Removes the display link from the run loop for the given mode.

[`invalidate()`](/documentation/QuartzCore/CADisplayLink/invalidate())

Removes the display link from all run loop modes.

## See Also

  <doc://com.apple.documentation/documentation/UIKit/presenting-content-on-a-connected-display>


---

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)