In SwiftUI, how do you make a loading indicator cycle through several looks with phaseAnimator, and what does adding a trigger change?
answer
- discrete steps, not one change
- a sequence of Equatable phases
- proxy plus current phase
- an animation per phase, or nil
- trigger: one pass per change
basics
~20 sApply phaseAnimator(_:content:animation:) (iOS 17) with a sequence of Equatable phases; SwiftUI animates each phase into the next and loops while the view is shown. With a trigger, it waits on the first phase and runs one pass per change.
solid answer
~40 s`phaseAnimator` (iOS 17) models motion as discrete steps. You pass a sequence of `Equatable` phases, often a `CaseIterable` enum, and a content closure that receives a proxy for the view plus the current phase, then apply modifiers such as `opacity` or `scaleEffect` based on that phase. When the view appears SwiftUI renders the first phase, immediately moves to the second and animates the difference, and keeps going until it loops back to the first. The optional `animation` closure returns an `Animation` per phase, or `nil` for a step that should not animate. The `phaseAnimator(_:trigger:content:animation:)` form instead rests on the first phase and runs through the phases each time the trigger value changes, which suits a one-shot reaction such as a tap.
code
swift · 31 linesimport SwiftUI
enum PulsePhase: CaseIterable {
case dim, bright, settle
var opacity: Double {
switch self {
case .dim: 0.3
case .bright: 1.0
case .settle: 0.6
}
}
var scale: Double {
self == .bright ? 1.2 : 1.0
}
}
struct LoadingDot: View {
var body: some View {
Circle()
.frame(width: 16, height: 16)
.phaseAnimator(PulsePhase.allCases) { content, phase in
content
.opacity(phase.opacity)
.scaleEffect(phase.scale)
} animation: { phase in
phase == .bright ? .snappy : .easeInOut(duration: 0.4)
}
}
}go deeper
Recall the two forms of phaseAnimator: the looping one that starts on appear and the trigger one that runs a pass per change, and that phases must be Equatable.
Explain the step sequence: first phase on appear, then each next phase animated with the closure's animation, nil meaning no animation, and the loop back to the first phase.
Show judgment about when discrete phases are enough and when independent per-property timing calls for keyframes, and how you end a looping indicator cleanly.
Frame phase animators as a shared vocabulary for small feedback motions, and weigh them against keyframes and designer-made assets for consistency and review cost.
## What a phase animator is A **phase animator** describes motion as a short list of discrete steps, called **phases**, and lets SwiftUI animate from each step to the next. It arrived in iOS 17 as the `PhaseAnimator` container and, more often used, the `phaseAnimator` view modifier. Apple's documentation describes it as a container that animates its content "by automatically cycling through a collection of phases that you provide, each defining a discrete step within an animation." The pieces you supply: - **`phases`** — any `Sequence` whose element type is `Equatable`. A two-step effect can use `[false, true]`; three or more steps usually read better as a `CaseIterable` enum, passed as `MyPhase.allCases`. - **`content`** — a closure that receives a proxy for the modified view and the current phase. You apply ordinary modifiers to the proxy (`opacity`, `scaleEffect`, `offset`, `rotationEffect`) with values chosen from the phase. - **`animation`** — an optional closure that receives a phase and returns the `Animation` to use for the move to the next phase. Return `nil` and that step happens without animation; omit the parameter and SwiftUI uses a default animation. Keeping the numbers on the enum as computed properties (`opacity`, `scale`, `verticalOffset`) keeps the content closure short, which is the shape Apple's own sample uses. The `animation` closure can then switch over the same named cases, so each step reads as a sentence: ease into the move, spring into the scale, settle smoothly back to the start. ## The looping form `phaseAnimator(_:content:animation:)` takes no trigger. When the view first appears, SwiftUI renders the content with the **first** phase. Right away it hands the content the **second** phase and animates the difference; when that animation completes it moves on to the next phase, and after the last one it loops back to the first. The result runs for as long as the view is on screen, which is exactly what a loading indicator needs: 1. List the looks the indicator passes through (dim, bright, settle). 2. Map each phase to modifier values. 3. Pick an animation per step, for example `.snappy` into the bright phase and a slower ease out of it. The looping modifier has no stop or pause parameter. To end the motion you remove the view, for example by showing the indicator only inside an `if isLoading` branch, or you switch to the trigger form. ## The trigger form `phaseAnimator(_:trigger:content:animation:)` adds a `trigger` of any `Equatable` type. The view sits on the first phase until the trigger value changes; each change runs the animator through its phases and back to the first. A counter of taps is the usual trigger, because every tap changes it. A bookmark icon that wiggles once per tap, or a badge that pulses when a new message arrives, fits this form. | | Looping form | Trigger form | |---|---|---| | Starts | When the view appears | When `trigger` changes | | Runs | Continuously, phase after phase | One pass through the phases per change | | Typical use | Loading indicators, attention pulses | A reaction to a tap or an event | ## How it relates to other animation tools A phase animator is built from the same machinery as `withAnimation`: in every step SwiftUI animates the difference between two sets of modifier values, so properties that can interpolate (opacity, scale, offset, rotation) move smoothly between phases. When you need different properties to move on independent timings, or exact durations per property, a **keyframe animator** is the better tool; when the motion is a function of elapsed time with no end state, a **`TimelineView`** is. ## Common mistakes - Wrapping the phase change in `withAnimation`: the animator advances by itself and animates each step with the closure's animation. - Passing an empty sequence: SwiftUI logs a runtime warning and shows a visual warning in place of the content. - Expecting the looping form to stop after one pass: it cycles until the view disappears. - Using the looping form for a one-shot reaction and toggling a Bool phase by hand, which fights the animator instead of giving it a trigger. - Forgetting accessibility: a looping indicator should respect the Reduce Motion setting, a concern that belongs to the accessibility material.
- How do you stop a looping phaseAnimator when loading finishes?The looping form has no stop or pause parameter, so you take it out of the hierarchy: show the indicator only inside an `if isLoading` branch, or replace it with a static view. If the motion should play only in response to events, use the `trigger:` form, which stays on the first phase until its value changes.
- When is [false, true] enough as the phases, and when do you need an enum?A Bool pair covers a two-step back-and-forth, such as moving up and back down. Once there are three or more steps, or each step sets several properties, a `CaseIterable` enum with computed properties per phase keeps the content closure readable and lets the `animation` closure switch over named cases.
- phaseAnimator needs a withAnimation call to move between phases.
- The looping phaseAnimator plays its phases once and then stops on the last one.
- Returning nil from the animation closure falls back to the default animation.
- Phases can be any type; they do not need to be Equatable.
- The trigger must be a Bool that you toggle back and forth.