CADisplayLink
CADisplayLink represents a timer synchronized with screen refreshes. It fires a tick event once for each frame the screen refreshes. Computing and setting the UI for that frame in the callback gives an animation driven entirely by code.
A new CADisplayLink doesn't start on its own. It starts firing only after you both listen for tick and call addToRunLoop() to add it to the main thread's event loop, NSRunLoop.mainRunLoop.
Once added, it keeps running until stopped. Even if your code doesn't keep a reference to it, it isn't garbage-collected, and the callback keeps running every frame. Always call invalidate() when you no longer need it.
For animations that can be expressed as "from one value to another" or "through a sequence of values", use an animation object: once an animation object is added to a layer, the system computes the intermediate value for each frame without running JS (this comes from iOS's definition and is not verified in the simulator). Every frame of a CADisplayLink runs a JS callback, and if JS is busy running other code, the callback waits until it finishes: the acceptance tests once measured the first frame arriving 2.07 seconds after addToRunLoop(), because JS was running other code the whole time. CADisplayLink suits cases that animation objects can't express: positions that depend on live data, your own physics simulation, game logic that needs a decision every frame.
Inheritance: EventTarget → NSObject → CADisplayLink
For how to use it for frame-by-frame animation, see the guide Running code every frame.
Constructor
Creates a CADisplayLink that isn't running yet.
Instance properties
| Property | Description |
|---|---|
isPaused | Whether firing tick is paused |
preferredFrameRateRange | How many callbacks per second you'd like |
timestamp read-only | The time of the most recent frame |
duration read-only | The interval between two frames |
targetTimestamp read-only | The time the most recent frame's content will be displayed |
Instance methods
| Method | Description |
|---|---|
addToRunLoop() | Starts it |
removeFromRunLoop() | Cancels callbacks for one mode |
invalidate() | Stops it for good |
Events
| Event | When it fires |
|---|---|
tick | Each frame the screen refreshes |
Examples
const link = new CADisplayLink();
link.addEventListener('tick', (ev) => {
const frame = /** @type {CADisplayLinkEvent} */ (ev).frame;
console.log('Frame time:', frame.timestamp);
});
link.addToRunLoop(NSRunLoop.mainRunLoop, { forMode: 'common' });Result: one line is logged to the console for each frame the screen refreshes.
Corresponding iOS API
| ObjC | JS |
|---|---|
[CADisplayLink displayLinkWithTarget:self selector:@selector(tick:)] | new CADisplayLink(), then addEventListener('tick', …) |
[link addToRunLoop:NSRunLoop.mainRunLoop forMode:NSRunLoopCommonModes] | link.addToRunLoop(NSRunLoop.mainRunLoop, { forMode: 'common' }) |
link.paused = YES | link.isPaused = true |
link.preferredFrameRateRange = CAFrameRateRangeMake(30, 60, 30) | link.preferredFrameRateRange = new CAFrameRateRange(30, 60, 30) |
See also
- Running code every frame
NSRunLoop: the first argument ofaddToRunLoop()- Structs:
CAFrameRateRange - How the runtime works: when callbacks run