ios-motion-and-animation

name	ios-motion-and-animation
description	iOS motion applied — the SwiftUI animation model (withAnimation, .animation(_:value:)), the modern spring-first defaults (.smooth/.snappy/.bouncy with duration:/bounce:, .spring, interpolatingSpring), transitions + matchedGeometryEffect + the iOS 18 .navigationTransition(.zoom), PhaseAnimator/KeyframeAnimator, rolling counters via .contentTransition(.numericText()), SF Symbol .symbolEffect, scroll-driven .scrollTransition/visualEffect, iOS 26 Liquid Glass morphing motion, haptics-synced .sensoryFeedback, recommended iOS timings, and Reduce Motion fallbacks. Use when animating any state change, transition, or micro-interaction on a native iOS screen.
tags	["ios","motion","animation","swiftui","hig","springs","reduce-motion"]

iOS motion & animation — spring-first, purposeful, reduce-motion-safe

Source: Apple HIG Motion (developer.apple.com/design/human-interface-guidelines/motion), SwiftUI Animation reference, WWDC23 "Animate with springs" (10158), WWDC25 "Build a SwiftUI app with the new design" (323) + "Get to know the new design system" (356), WWDC26 "What's new in SwiftUI" + "Build powerful drag and drop in SwiftUI" (271) + the iOS 27 Liquid Glass refinements keynote, cross-checked across research passes against technical references (createwithswift, nilcoalescing, GetStream spring catalog, swiftwithmajid, arshtechpro) — June 2026. iOS 26 = shipping baseline; iOS 27 (WWDC 2026, June 8–12 2026) = current cycle — the spring model, transitions, matchedGeometryEffect, .numericText(), .symbolEffect, and Liquid Glass morphing all carry forward; iOS 27 adds Liquid Glass v2 motion tuning + drag-to-reorder/scroll-minimize transition APIs (§§10, 16). Apple's rule: motion is purposeful — it conveys feedback, status, and continuity; it is never decoration; and it is always optional (Reduce Motion).

1. The SwiftUI animation model

Two ways to animate; both interpolate from the current value to the new one when state changes.

// (a) withAnimation — wrap the state mutation; everything depending on it animates
withAnimation(.snappy) { isExpanded.toggle() }

// (b) .animation(_:value:) — scoped, declarative; fires only when `value` changes
ringFill
    .animation(.smooth(duration: 0.4), value: caloriesConsumed)  // PREFER — scoped

Always use the value: form. The deprecated .animation(_) (no value) animates on every change and is a top source of jank. Animate the smallest view that needs it, not a whole screen. withAnimation returns its closure's result and takes an optional completion: (iOS 17+) for chaining.

2. Curves vs springs — prefer springs

Easing curves (use only for non-spatial, finite changes — opacity, color):

Curve	SwiftUI	Feel
Linear	.linear(duration:)	constant speed — only for continuous loops/progress
Ease-in	.easeIn	accelerates — for exits
Ease-out	.easeOut	decelerates — for entrances
Ease-in-out	.easeInOut	the classic default; symmetric

Default static duration for the ease curves is 0.35 s. .default ≈ a system ease-in-out.

Springs are the modern default for anything spatial (position, scale, anything that follows a gesture or a tap). They are interruptible and re-target gracefully mid-flight, which curves cannot.

3. Springs — the WWDC23 duration/bounce model (use this)

WWDC23 reframed springs around two intuitive params, replacing response/dampingFraction guesswork:

• duration — perceptual settle time (≈ how long it feels like it takes), default 0.5 s.
• bounce — 0 = no overshoot (smooth), ~0.3 = noticeably springy, >0.4 = exaggerated/cartoonish.

Three named presets, all defaulting to duration: 0.5, extraBounce: 0.0, differing only in built-in bounce:

Preset	Bounce / damping	Use for
.smooth	bounce 0, critically damped — no overshoot	most UI: sheets, layout, fades, color-blocked tiles
.snappy	slightly underdamped, tiny overshoot	taps, toggles, selection — lively but controlled
.bouncy	clearly underdamped, visible overshoot	celebratory / playful moments only

withAnimation(.snappy) { … }                       // preset
withAnimation(.smooth(duration: 0.4)) { … }         // tune duration
withAnimation(.bouncy(duration: 0.5, extraBounce: 0.15)) { … }  // add bounce on top
withAnimation(.spring(duration: 0.5, bounce: 0.3)) { … }        // explicit spring
withAnimation(.interactiveSpring) { … }             // for gesture-driven, low-latency tracking

interpolatingSpring is additive — overlapping calls stack velocity (use when many rapid changes should compound, e.g. flick-scrolling). The plain presets blend (a new spring smoothly retargets the old). Legacy .spring(response:0.55, dampingFraction:0.825) and .interactiveSpring(response:0.15, dampingFraction:0.86, blendDuration:0.25) still work; prefer the duration/bounce form for new code.

Verify-at-source flag: the exact internal bounce of .snappy (commonly cited ≈ 0.15) and .bouncy (≈ 0.3) is not stated in Apple's reference — only that smooth = 0 and the presets sit at fixed points on the spectrum. Confirm feel on-device; don't quote a precise snappy/bouncy bounce number as Apple-official.

4. Transitions — views entering/leaving the hierarchy

.transition(_) defines how a view animates in/out when inserted/removed inside a withAnimation block.

if showCard {
    AdaptationCard()
        .transition(.move(edge: .bottom).combined(with: .opacity))  // slide up + fade
}
withAnimation(.smooth) { showCard = true }

Building blocks: .opacity, .scale(scale:anchor:), .move(edge:), .push(from:), .slide, .blurReplace (iOS 17+), .identity. Use .asymmetric(insertion:removal:) when in ≠ out (common: scale+fade in, fade out). Combine with .combined(with:). .contentTransition(...) handles content within a stable view changing (see §6).

5. matchedGeometryEffect & the iOS 18 zoom transition

matchedGeometryEffect(id:in:) morphs one element into another across a layout change within the same view tree (shared-element). Pair with @Namespace.

iOS 18 .navigationTransition(.zoom) is the simpler, cross-presentation successor — it works across navigation pushes and sheets where matchedGeometryEffect is fragile:

@Namespace private var ns
NavigationLink { MealDetailView() }
    .matchedTransitionSource(id: meal.id, in: ns)   // source
// on the destination:
MealDetailView().navigationTransition(.zoom(sourceID: meal.id, in: ns))

Use zoom for tapping a meal/photo thumbnail that expands into a full detail screen. Available iOS 18+, carries forward to iOS 27 unchanged. iOS 27 adds a sibling .navigationTransition(.crossFade) — a system cross-dissolve for pushes/presentations where a spatial zoom would be wrong (e.g. switching between peer detail screens, or content with no clear source rect); it's also the natural match for the Reduce Motion cross-fade rule in §13.

6. Rolling numeric counters — .contentTransition(.numericText())

The premium way to animate a calorie/macro number changing — digits roll rather than hard-cut. Must wrap the change in an animation and pin digit width:

Text(calories, format: .number)
    .font(.system(.largeTitle, design: .rounded)).monospacedDigit()
    .contentTransition(.numericText(value: Double(calories)))   // value: drives roll direction
// trigger:
withAnimation(.snappy) { calories = newTotal }

.numericText(countsDown:) for downward counts. Other content transitions: .opacity, .interpolate, .symbolEffect (for SF Symbol swaps).

7. PhaseAnimator & KeyframeAnimator (iOS 17+)

• PhaseAnimator — steps through an ordered set of discrete phases, animating between each. For multi-step sequences (e.g. a success checkmark: scale up → settle → glow). Drive once with a trigger, or loop.
• KeyframeAnimator — independent property timelines (scale, rotation, offset each on their own keyframe track). For richer choreographed one-shots.

checkmark.phaseAnimator([0.0, 1.2, 1.0], trigger: didLogMeal) { view, scale in
    view.scaleEffect(scale)
} animation: { _ in .bouncy(duration: 0.4) }

Reach for these only when a single spring/transition can't express the sequence — most micro-interactions don't need them.

8. SF Symbol motion — .symbolEffect

System-integrated icon animation; prefer over hand-rolling scale/opacity on an Image.

Effect	Behavior	iOS
.bounce	one-shot scale pop (great on tap success)	17
.pulse	opacity throb, repeats	17
.variableColor	layers light in sequence (recording/loading)	17
.scale (.up/.down)	state-held scale	17
.replace	morph one symbol into another	17
.wiggle, .rotate, .breathe	shake / rotate / subtle pulse	18
.appear / .disappear	animated insert/remove	17

Image(systemName: "checkmark.circle.fill").symbolEffect(.bounce, value: didLog)
Image(systemName: isRecording ? "mic.fill" : "mic")
    .contentTransition(.symbolEffect(.replace))   // morph on state change

Indefinite effects (.pulse, .breathe, .variableColor, .rotate) repeat while active — stop them when the state ends, or they read as nervous UI.

9. Scroll-driven effects — .scrollTransition & visualEffect

.scrollTransition animates a cell as it enters/leaves the viewport; phase is .identity / .topLeading / .bottomTrailing, with a continuous value −1.0 … 1.0.

RecipeCookCard()
    .scrollTransition { content, phase in
        content.opacity(phase.isIdentity ? 1 : 0.4)
               .scaleEffect(phase.isIdentity ? 1 : 0.92)
    }

visualEffect { content, proxy in … } reads the view's own geometry (via GeometryProxy) to drive effects without restructuring the tree — e.g. a parallax header. .scrollPosition(id:) / .scrollTargetBehavior(.viewAligned) give snap + position binding. Keep scroll effects subtle — heavy per-cell transforms tank scroll FPS.

10. Liquid Glass — fluid, morphing motion (iOS 26 baseline, iOS 27 v2)

Liquid Glass elements morph (don't cut) as they appear, merge, and separate. Motion is built into the material, not added on top.

• Wrap related glass elements in a GlassEffectContainer(spacing:); the spacing is the merge threshold — within it, shapes fluidly blend into one during transitions.
• Give morphing pairs a shared .glassEffectID(_:in:) so SwiftUI animates the glass shape transforming between states.
• .interactive() on .glassEffect() adds the system press response: the glass scales, bounces, and shimmers on touch — get this free instead of faking it.
• iOS 26 sheets are inset with a glass background that morphs to opaque + edge-anchored as they grow to full height; partial detents nest into the display's corner radius. Don't override this with custom sheet animation.

GlassEffectContainer(spacing: 24) {
    macroTilePink.glassEffect().glassEffectID("protein", in: ns)
    macroTileMint.glassEffect().glassEffectID("carbs", in: ns)
}

iOS 27 — Liquid Glass v2 motion + the transparency slider. Apple retuned the material so it diffuses content behind it more and adds more depth/separation — the morph choreography is unchanged, but moving glass reads cleaner over busy content, so heavy custom motion behind glass is even less necessary. iOS 27 adds a system-level transparency slider (Settings + first-run setup) letting users dial glass translucency down to fully opaque; SwiftUI's .glassEffect() and tint respond automatically — apps recompiled on the 2027 SDK pick it up with no code change. Practical motion rule: don't hard-code an assumed glass opacity into a custom animation (e.g. a fade timed to a translucency you guessed) — read state via the appearsActive environment value rather than assuming, since the user may have reduced glass to opaque. This is a currency/readability refinement, not a new motion API.

11. Haptics-synced motion — .sensoryFeedback

Pair a meaningful animation with feedback (iOS 17+ SwiftUI API; no UIFeedbackGenerator needed). Fire on the same state change that drives the animation so touch and motion land together.

.sensoryFeedback(.success, trigger: didLogMeal)        // .success/.warning/.error/.selection/.impact
.sensoryFeedback(.selection, trigger: selectedMacro)   // light tick on segment change

Haptics are punctuation, not a soundtrack — one per discrete confirmation, never on every scroll tick. See ios-gestures-and-haptics.

12. Recommended iOS timings

• Micro-feedback (tap, toggle, selection): .snappy or ~0.2–0.3 s.
• Standard UI (sheets, layout, card in/out, counters): .smooth ~0.3–0.5 s (presets default to 0.5).
• Large/celebratory: up to ~0.6 s; add bounce only here.
• Continuous (spinners, indeterminate progress): .linear.repeatForever(autoreverses:false). Faster than ~0.15 s reads as a glitch; slower than ~0.6 s for routine UI reads as sluggish. Tie speed to spatial distance — bigger move, slightly longer.

13. Reduce Motion (non-negotiable)

~1 in 3 users report motion sensitivity; large position/scale/parallax animation can trigger vestibular discomfort. Honor the system setting:

@Environment(\.accessibilityReduceMotion) private var reduceMotion

withAnimation(reduceMotion ? .easeInOut(duration: 0.2) : .bouncy) { … }
.transition(reduceMotion ? .opacity : .move(edge: .bottom).combined(with: .opacity))

Rule: replace slide/scale/zoom/spring with a cross-fade (.opacity) or no animation — never with a faster slide. Disable: parallax, looping/auto-playing motion, big zoom/PhaseAnimator celebrations, decorative symbolEffect loops. Counter rolls and a checkmark fade are acceptable; a bouncing zoom is not. (Apple also surfaces "Prefer Cross-Fade Transitions" under Reduce Motion — your code only needs to read accessibilityReduceMotion.) System Liquid Glass + standard transitions already adapt; your custom motion is what you must gate.

14. Mistakes that read as cheap / amateur

Easing curves where springs belong (spatial motion feels dead) · .animation(_) without value: (animates everything, janky) · linear easing on UI (robotic) · over-bouncing — .bouncy/bounce > 0.4 on routine UI · everything ~1 s (sluggish) · hard-cutting numbers instead of .numericText() · indefinite symbolEffect/.pulse left running (nervous UI) · re-implementing Liquid Glass press feedback instead of .interactive() · heavy per-cell scrollTransition transforms (dropped frames) · ignoring Reduce Motion, or "honoring" it with a faster slide instead of a cross-fade.

16. iOS 27 — drag-to-reorder, scroll-minimize & swipe motion (WWDC 2026)

New interaction motion APIs; SwiftUI owns the animation — don't hand-roll the drag/slide.

• Drag-to-reorder, any container — apply .reorderable() to a ForEach and .reorderContainer(for:_:) to the parent; the lift, gap-open, and settle are driven by SwiftUI. Works beyond List (e.g. LazyVGrid) and reaches watchOS for the first time. The end closure hands you a ReorderDifference (sources + a .before(id) / .end destination) — apply it to your model; the animation is automatic, so don't wrap the data mutation in a competing withAnimation spring.
• Nav-bar minimize on scroll — .toolbarMinimizeBehavior(.onScrollDown, for: .navigationBar) collapses the navigation bar as content scrolls and restores it on scroll-up; a system transition — let it run rather than animating a custom sticky header.
• Swipe actions beyond List — .swipeActions() now works in ScrollView / lazy stacks / custom layouts when the scroll container is marked with .swipeActionsContainer(); the reveal/commit motion is system-standard.

Verify-at-source flag: these names match WWDC26 session/community coverage (session 271 "Build powerful drag and drop in SwiftUI") but the exact signatures (.reorderContainer(for:_:) argument shape, appearsActive semantics) shifted across betas — confirm against the iOS 27 SDK / current Apple docs before shipping, and don't quote a precise closure signature as final.

17. Greg application

Cobalt #2C50F0 primary, Figtree Medium display, color-blocked macro tiles (pink/yellow/mint), black photo-detail log screen, metrics on Progress, F21 home-screen widgets.

• Calorie ring fill: animate the trim with .smooth(duration: 0.4) on value: caloriesConsumed; let the cobalt arc sweep, never snap. The center number rolls via .contentTransition(.numericText()) + .monospacedDigit(), triggered in the same withAnimation.
• Macro tiles (pink/yellow/mint): on log, .snappy the height/value change; a .symbolEffect(.bounce, value:) on the tile's SF Symbol; light .sensoryFeedback(.selection, ...). Keep bounce subtle — these are data, not toys.
• Adaptation card entrance: .transition(.move(edge: .bottom).combined(with: .opacity)) inside withAnimation(.smooth); if it's a hero suggestion, a single .snappy settle, not .bouncy.
• Photo-detail log screen (black): tap a meal thumbnail → .navigationTransition(.zoom(sourceID:in:)) so the photo expands into the detail; pair with matchedTransitionSource on the grid cell.
• Streak celebration (Progress): a one-shot PhaseAnimator (scale 0→1.2→1) + .bouncy(duration: 0.4) + .sensoryFeedback(.success, ...) — the only place bounce is warranted.
• Widgets (F21): WidgetKit animates value changes automatically on timeline refresh; use .contentTransition(.numericText()) on the calorie/macro readout. No interactive/looping motion in widgets.
• Reorderable lists (iOS 27, where a list is user-ordered — saved logs, a grocery list): prefer .reorderable() + .reorderContainer(for:_:) over a hand-built drag gesture; let SwiftUI drive the lift/settle, apply the ReorderDifference to the store, and don't wrap the model write in a competing spring. Reserve for genuinely ordered lists — don't add drag affordances to read-only feeds.
• Reduce Motion fallback (ship in the same slice): gate every spatial animation above — ring fills as a .opacity cross-fade (no sweep), zoom → fade, streak celebration → a static state, no parallax. Counter rolls may stay (purely textual). Test at the largest a11y text size with Reduce Motion on.

Pairs with: ios-components (sheets/bars motion), ios-color-and-materials (Liquid Glass), ios-gestures-and-haptics (sensoryFeedback + interruptible springs), accessibility-and-inclusive-design (Reduce Motion / vestibular safety).