SF Symbols — API Reference

When to Use This Skill

Use when:

• You need exact API signatures for rendering modes or symbol effects
• You need UIKit/AppKit equivalents for SwiftUI symbol APIs
• You need to check platform availability for a specific effect
• You need configuration options (weight, scale, variable values)
• You need to create custom symbols with proper template structure

Related Skills

• Use axiom-sf-symbols for decision trees, anti-patterns, troubleshooting, and when to use which effect
• Use axiom-swiftui-animation-ref for general SwiftUI animation (non-symbol)

---

Part 1: Symbol Display

SwiftUI

// Basic display
Image(systemName: "star.fill")

// With Label (icon + text)
Label("Favorites", systemImage: "star.fill")

// Font sizing — symbol scales with text
Image(systemName: "star.fill")
    .font(.title)

// Image scale — relative sizing without changing font
Image(systemName: "star.fill")
    .imageScale(.large) // .small, .medium, .large

// Explicit point size
Image(systemName: "star.fill")
    .font(.system(size: 24))

// Weight — matches SF Pro font weights
Image(systemName: "star.fill")
    .fontWeight(.bold) // .ultraLight through .black

// Symbol variant — programmatic .fill, .circle, .square, .slash
Image(systemName: "person")
    .symbolVariant(.circle.fill) // Renders person.circle.fill

// Variable value — 0.0 to 1.0, controls symbol fill level
Image(systemName: "speaker.wave.3.fill", variableValue: 0.5)

UIKit

// Basic display
let image = UIImage(systemName: "star.fill")
imageView.image = image

// Configuration — point size and weight
let config = UIImage.SymbolConfiguration(pointSize: 24, weight: .bold)
let image = UIImage(systemName: "star.fill", withConfiguration: config)

// Configuration — text style (scales with Dynamic Type)
let config = UIImage.SymbolConfiguration(textStyle: .title1)
let image = UIImage(systemName: "star.fill", withConfiguration: config)

// Configuration — scale
let config = UIImage.SymbolConfiguration(scale: .large) // .small, .medium, .large

// Combine configurations
let sizeConfig = UIImage.SymbolConfiguration(pointSize: 24, weight: .bold, scale: .large)

// Variable value
let image = UIImage(systemName: "speaker.wave.3.fill", variableValue: 0.5)

AppKit

// Basic display
let image = NSImage(systemSymbolName: "star.fill", accessibilityDescription: "Favorite")

// Configuration
let config = NSImage.SymbolConfiguration(pointSize: 24, weight: .bold)
let configured = image?.withSymbolConfiguration(config)

---

Part 2: Rendering Modes

SwiftUI

// Monochrome (default)
Image(systemName: "cloud.rain.fill")
    .foregroundStyle(.blue)

// Hierarchical — depth from single color
Image(systemName: "cloud.rain.fill")
    .symbolRenderingMode(.hierarchical)
    .foregroundStyle(.blue)

// Palette — explicit color per layer
Image(systemName: "cloud.rain.fill")
    .symbolRenderingMode(.palette)
    .foregroundStyle(.white, .blue)
// For 3-layer symbols:
    .foregroundStyle(.red, .white, .blue)

// Multicolor — Apple's curated colors
Image(systemName: "cloud.rain.fill")
    .symbolRenderingMode(.multicolor)

// Preferred rendering mode — uses symbol's preferred mode
// Falls back gracefully if the symbol doesn't support it
Image(systemName: "cloud.rain.fill")
    .symbolRenderingMode(.monochrome) // explicit monochrome

SymbolRenderingMode Enum

Value	Description
.monochrome	Single color for all layers (default)
.hierarchical	Single color with automatic opacity per layer
.palette	Explicit color per layer via .foregroundStyle()
.multicolor	Apple's fixed curated colors

UIKit

// Hierarchical
let config = UIImage.SymbolConfiguration(hierarchicalColor: .systemBlue)
imageView.preferredSymbolConfiguration = config

// Palette
let config = UIImage.SymbolConfiguration(paletteColors: [.white, .systemBlue])
imageView.preferredSymbolConfiguration = config

// Multicolor
let config = UIImage.SymbolConfiguration.preferringMulticolor()
imageView.preferredSymbolConfiguration = config

// Monochrome — just set tintColor
imageView.tintColor = .systemBlue

Combining Configurations (UIKit)

let sizeConfig = UIImage.SymbolConfiguration(pointSize: 24, weight: .bold)
let colorConfig = UIImage.SymbolConfiguration(paletteColors: [.white, .blue, .gray])
let combined = sizeConfig.applying(colorConfig)
imageView.preferredSymbolConfiguration = combined

---

Part 3: Symbol Effects — Complete API

Effect Protocol Hierarchy

All symbol effects conform to SymbolEffect. Sub-protocols define behavior:

Protocol	Trigger	Modifier	Loop
DiscreteSymbolEffect	value: (Equatable)	.symbolEffect(_:options:value:)	No
IndefiniteSymbolEffect	isActive: (Bool)	.symbolEffect(_:options:isActive:)	Yes
TransitionSymbolEffect	View lifecycle	.transition(.symbolEffect(_:))	No
ContentTransitionSymbolEffect	Symbol change	.contentTransition(.symbolEffect(_:))	No

Remove All Effects (SwiftUI)

// Strip all symbol effects from a view hierarchy
Image(systemName: "star.fill")
    .symbolEffectsRemoved() // Removes all effects
    .symbolEffectsRemoved(false) // Re-enables effects

SymbolEffectOptions

// Speed multiplier
.symbolEffect(.bounce, options: .speed(2.0), value: count)

// Repeat count
.symbolEffect(.bounce, options: .repeat(3), value: count)

// Continuous repeat
.symbolEffect(.pulse, options: .repeat(.continuous), isActive: true)

// Non-repeating (for indefinite effects, run once then hold)
.symbolEffect(.breathe, options: .nonRepeating, isActive: true)

// Combined
.symbolEffect(.wiggle, options: .repeat(5).speed(1.5), value: count)

---

Bounce

Protocols: DiscreteSymbolEffect

// Discrete — triggers on value change
Image(systemName: "arrow.down.circle")
    .symbolEffect(.bounce, value: downloadCount)

// Directional
    .symbolEffect(.bounce.up, value: count)
    .symbolEffect(.bounce.down, value: count)

// By Layer — different layers bounce at different times
    .symbolEffect(.bounce.byLayer, value: count)

// Whole Symbol — entire symbol bounces together
    .symbolEffect(.bounce.wholeSymbol, value: count)

UIKit:

imageView.addSymbolEffect(.bounce)
// With options:
imageView.addSymbolEffect(.bounce, options: .repeat(3))

---

Pulse

Protocols: DiscreteSymbolEffect, IndefiniteSymbolEffect

// Indefinite — continuous while active
Image(systemName: "network")
    .symbolEffect(.pulse, isActive: isConnecting)

// Discrete — triggers once on value change
    .symbolEffect(.pulse, value: errorCount)

// By Layer
    .symbolEffect(.pulse.byLayer, isActive: true)

// Whole Symbol
    .symbolEffect(.pulse.wholeSymbol, isActive: true)

UIKit:

imageView.addSymbolEffect(.pulse)
imageView.removeSymbolEffect(ofType: PulseSymbolEffect.self)

---

Variable Color

Protocols: DiscreteSymbolEffect, IndefiniteSymbolEffect

// Iterative — highlights one layer at a time
Image(systemName: "wifi")
    .symbolEffect(.variableColor.iterative, isActive: isSearching)

// Cumulative — progressively fills layers
    .symbolEffect(.variableColor.cumulative, isActive: true)

// Reversing — cycles back and forth
    .symbolEffect(.variableColor.iterative.reversing, isActive: true)

// Hide inactive layers (dims non-highlighted layers)
    .symbolEffect(.variableColor.iterative.hideInactiveLayers, isActive: true)

// Dim inactive layers (slightly reduces opacity of non-highlighted)
    .symbolEffect(.variableColor.iterative.dimInactiveLayers, isActive: true)

UIKit:

imageView.addSymbolEffect(.variableColor.iterative)
imageView.removeSymbolEffect(ofType: VariableColorSymbolEffect.self)

---

Scale

Protocols: IndefiniteSymbolEffect

// Scale up
Image(systemName: "mic.fill")
    .symbolEffect(.scale.up, isActive: isRecording)

// Scale down
    .symbolEffect(.scale.down, isActive: isMuted)

// By Layer
    .symbolEffect(.scale.up.byLayer, isActive: true)

// Whole Symbol
    .symbolEffect(.scale.up.wholeSymbol, isActive: true)

UIKit:

imageView.addSymbolEffect(.scale.up)
imageView.removeSymbolEffect(ofType: ScaleSymbolEffect.self)

---

Wiggle (iOS 18+)

Protocols: DiscreteSymbolEffect, IndefiniteSymbolEffect

// Discrete
Image(systemName: "bell.fill")
    .symbolEffect(.wiggle, value: notificationCount)

// Directional
    .symbolEffect(.wiggle.left, value: count)
    .symbolEffect(.wiggle.right, value: count)
    .symbolEffect(.wiggle.forward, value: count)  // RTL-aware
    .symbolEffect(.wiggle.backward, value: count)  // RTL-aware
    .symbolEffect(.wiggle.up, value: count)
    .symbolEffect(.wiggle.down, value: count)
    .symbolEffect(.wiggle.clockwise, value: count)
    .symbolEffect(.wiggle.counterClockwise, value: count)

// Custom angle
    .symbolEffect(.wiggle.custom(angle: .degrees(15)), value: count)

// By Layer
    .symbolEffect(.wiggle.byLayer, value: count)

UIKit:

imageView.addSymbolEffect(.wiggle)

---

Rotate (iOS 18+)

Protocols: DiscreteSymbolEffect, IndefiniteSymbolEffect

// Indefinite rotation
Image(systemName: "gear")
    .symbolEffect(.rotate, isActive: isProcessing)

// Direction
    .symbolEffect(.rotate.clockwise, isActive: true)
    .symbolEffect(.rotate.counterClockwise, isActive: true)

// By Layer — only specific layers rotate (e.g., fan blades)
    .symbolEffect(.rotate.byLayer, isActive: true)

UIKit:

imageView.addSymbolEffect(.rotate)
imageView.removeSymbolEffect(ofType: RotateSymbolEffect.self)

---

Breathe (iOS 18+)

Protocols: DiscreteSymbolEffect, IndefiniteSymbolEffect

// Basic breathe
Image(systemName: "heart.fill")
    .symbolEffect(.breathe, isActive: isMonitoring)

// Plain — scale only
    .symbolEffect(.breathe.plain, isActive: true)

// Pulse — scale + opacity variation
    .symbolEffect(.breathe.pulse, isActive: true)

// By Layer
    .symbolEffect(.breathe.byLayer, isActive: true)

UIKit:

imageView.addSymbolEffect(.breathe)
imageView.removeSymbolEffect(ofType: BreatheSymbolEffect.self)

---

Appear and Disappear

Protocols: TransitionSymbolEffect

// SwiftUI transition
if showSymbol {
    Image(systemName: "checkmark.circle.fill")
        .transition(.symbolEffect(.appear))
}

if showSymbol {
    Image(systemName: "xmark.circle.fill")
        .transition(.symbolEffect(.disappear))
}

// Directional
    .transition(.symbolEffect(.appear.up))
    .transition(.symbolEffect(.appear.down))
    .transition(.symbolEffect(.disappear.up))
    .transition(.symbolEffect(.disappear.down))

// By Layer
    .transition(.symbolEffect(.appear.byLayer))

// Whole Symbol
    .transition(.symbolEffect(.appear.wholeSymbol))

UIKit (as effect, not transition):

// Make symbol appear
imageView.addSymbolEffect(.appear)

// Make symbol disappear
imageView.addSymbolEffect(.disappear)

// Appear after disappear
imageView.addSymbolEffect(.appear) // re-shows hidden symbol

---

Replace

Protocols: ContentTransitionSymbolEffect

// SwiftUI content transition
Image(systemName: isFavorite ? "star.fill" : "star")
    .contentTransition(.symbolEffect(.replace))

// Directional variants
    .contentTransition(.symbolEffect(.replace.downUp))
    .contentTransition(.symbolEffect(.replace.upUp))
    .contentTransition(.symbolEffect(.replace.offUp))

// By Layer
    .contentTransition(.symbolEffect(.replace.byLayer))

// Whole Symbol
    .contentTransition(.symbolEffect(.replace.wholeSymbol))

// Magic Replace — default in iOS 18+, morphs shared elements
// Automatic for structurally related pairs: star ↔ star.fill, pause.fill ↔ play.fill
    .contentTransition(.symbolEffect(.replace))

// Explicit Magic Replace with fallback for unrelated symbols
    .contentTransition(.symbolEffect(.replace.magic(fallback: .replace.downUp)))

UIKit:

// Change symbol with Replace transition
let newImage = UIImage(systemName: "star.fill")
imageView.setSymbolImage(newImage!, contentTransition: .replace)

// Directional
imageView.setSymbolImage(newImage!, contentTransition: .replace.downUp)

---

Part 4: Draw Effects (iOS 26+)

Draw On

// Indefinite — draws in while active
Image(systemName: "checkmark.circle")
    .symbolEffect(.drawOn, isActive: isComplete)

// Playback modes
    .symbolEffect(.drawOn.byLayer, isActive: isActive)
    .symbolEffect(.drawOn.wholeSymbol, isActive: isActive)
    .symbolEffect(.drawOn.individually, isActive: isActive)

// With options
    .symbolEffect(.drawOn, options: .speed(2.0), isActive: isActive)
    .symbolEffect(.drawOn, options: .nonRepeating, isActive: isActive)

Draw Off

// Indefinite — draws out while active
Image(systemName: "star.fill")
    .symbolEffect(.drawOff, isActive: isHidden)

// Playback modes
    .symbolEffect(.drawOff.byLayer, isActive: isActive)
    .symbolEffect(.drawOff.wholeSymbol, isActive: isActive)
    .symbolEffect(.drawOff.individually, isActive: isActive)

// Direction control
    .symbolEffect(.drawOff.nonReversed, isActive: isActive) // follows draw path forward
    .symbolEffect(.drawOff.reversed, isActive: isActive)    // erases in reverse order

UIKit Draw Effects

// Draw On
imageView.addSymbolEffect(.drawOn)

// Draw Off
imageView.addSymbolEffect(.drawOff)

// Remove
imageView.removeSymbolEffect(ofType: DrawOnSymbolEffect.self)

Variable Draw

Uses SymbolVariableValueMode to control how variable values are rendered.

// Variable Draw — draws stroke proportional to value (iOS 26+)
Image(systemName: "thermometer.high", variableValue: temperature)
    .symbolVariableValueMode(.draw)

// Variable Color — sets layer opacity based on threshold (iOS 17+, default)
Image(systemName: "wifi", variableValue: signalStrength)
    .symbolVariableValueMode(.color)

SymbolVariableValueMode Enum (iOS 26+)

Case	Description
.color	Sets opacity of each variable layer on/off based on threshold (existing behavior)
.draw	Changes drawn length of each variable layer based on range

Constraint: Some symbols support only one mode. Setting an unsupported mode has no visible effect. A symbol cannot use both Variable Color and Variable Draw simultaneously.

Gradient Rendering (iOS 26+)

Uses SymbolColorRenderingMode for automatic gradient generation from a single color.

// Gradient fill — system generates axial gradient from source color
Image(systemName: "heart.fill")
    .symbolColorRenderingMode(.gradient)
    .foregroundStyle(.red)

// Works with any rendering mode
Image(systemName: "cloud.rain.fill")
    .symbolRenderingMode(.hierarchical)
    .symbolColorRenderingMode(.gradient)
    .foregroundStyle(.blue)

SymbolColorRenderingMode Enum (iOS 26+)

Case	Description
.flat	Solid color fill (default)
.gradient	Axial gradient generated from source color

Gradients are most effective at larger symbol sizes and work across all rendering modes.

---

Part 5: Content Transition Patterns

Symbol Swap with Replace

struct PlayPauseButton: View {
    @State private var isPlaying = false

    var body: some View {
        Button {
            isPlaying.toggle()
        } label: {
            Image(systemName: isPlaying ? "pause.fill" : "play.fill")
                .contentTransition(.symbolEffect(.replace))
        }
        .accessibilityLabel(isPlaying ? "Pause" : "Play")
    }
}

Download Progress Pattern

struct DownloadButton: View {
    @State private var state: DownloadState = .idle

    var symbolName: String {
        switch state {
        case .idle: "arrow.down.circle"
        case .downloading: "stop.circle"
        case .complete: "checkmark.circle.fill"
        }
    }

    var body: some View {
        Button {
            advanceState()
        } label: {
            Image(systemName: symbolName)
                .contentTransition(.symbolEffect(.replace))
                .symbolEffect(.pulse, isActive: state == .downloading)
        }
    }
}

Toggle with Effect Feedback

struct FavoriteButton: View {
    @Binding var isFavorite: Bool
    @State private var bounceValue = 0

    var body: some View {
        Button {
            isFavorite.toggle()
            bounceValue += 1
        } label: {
            Image(systemName: isFavorite ? "star.fill" : "star")
                .contentTransition(.symbolEffect(.replace))
                .symbolEffect(.bounce, value: bounceValue)
                .foregroundStyle(isFavorite ? .yellow : .gray)
        }
    }
}

---

Part 6: Custom Symbols

Template Structure

Custom symbols are SVG files with specific layer annotations:

1. Export from design tool as SVG
2. Import into SF Symbols app (File > Import)
3. Set template type: Monochrome, Hierarchical, Multicolor, or Variable Color
4. Annotate layers for rendering modes:
   • Primary layer: Full opacity in Hierarchical
   • Secondary layer: Reduced opacity in Hierarchical
   • Tertiary layer: Most reduced opacity in Hierarchical
5. Set Palette colors per layer if supporting Palette mode
6. Export as .svg template for Xcode

Draw Annotation (SF Symbols 7)

To enable Draw animations on custom symbols:

1. Select a path in SF Symbols 7 app
2. Open the Draw annotation panel
3. Place guide points on the path:

Point Type	Visual	Purpose
Start	Open circle	Where drawing begins
End	Closed circle	Where drawing ends
Corner	Diamond	Sharp direction change
Bidirectional	Double arrow	Center-outward drawing
Attachment	Link icon	Non-drawing decorative connection

4. Minimum: 2 guide points per path (start + end)
5. Option-drag for precise placement
6. Test in Preview panel across all weights

Weight Interpolation

Custom symbols should include designs for at least 3 weight variants:

• Ultralight (thinnest)
• Regular (middle)
• Black (thickest)

The system interpolates between these for intermediate weights (Thin, Light, Medium, Semibold, Bold, Heavy).

Importing to Xcode

1. In Xcode, open Asset Catalog
2. Click + > Symbol Image Set
3. Drag exported .svg from SF Symbols app
4. Asset catalog symbols: Image("custom.symbol.name"). For symbols loaded from a bundle: Image(systemName: "custom.symbol.name", bundle: .module)

---

Part 7: Platform Availability Matrix

Rendering Modes

Feature	iOS	macOS	watchOS	tvOS	visionOS
Monochrome	13+	11+	6+	13+	1+
Hierarchical	15+	12+	8+	15+	1+
Palette	15+	12+	8+	15+	1+
Multicolor	15+	12+	8+	15+	1+
Variable Value	16+	13+	9+	16+	1+

Symbol Effects

Effect	Category	iOS	macOS	watchOS	tvOS	visionOS
Bounce	Discrete	17+	14+	10+	17+	1+
Pulse	Discrete/Indefinite	17+	14+	10+	17+	1+
Variable Color	Discrete/Indefinite	17+	14+	10+	17+	1+
Scale	Indefinite	17+	14+	10+	17+	1+
Appear	Transition	17+	14+	10+	17+	1+
Disappear	Transition	17+	14+	10+	17+	1+
Replace	Content Transition	17+	14+	10+	17+	1+
Wiggle	Discrete/Indefinite	18+	15+	11+	18+	2+
Rotate	Discrete/Indefinite	18+	15+	11+	18+	2+
Breathe	Discrete/Indefinite	18+	15+	11+	18+	2+
Draw On	Indefinite	26+	Tahoe+	26+	26+	26+
Draw Off	Indefinite	26+	Tahoe+	26+	26+	26+
Variable Draw	Value-based	26+	Tahoe+	26+	26+	26+
Gradient Fill	Rendering	26+	Tahoe+	26+	26+	26+

Effect Behavior Categories

Category	What It Does	How to Trigger
Discrete	One-shot animation, returns to rest	.symbolEffect(_:value:) — fires when value changes
Indefinite	Loops while active	.symbolEffect(_:isActive:) — loops while true
Transition	Plays on view insert/remove	.transition(.symbolEffect(_:))
Content Transition	Plays when symbol changes	.contentTransition(.symbolEffect(_:))

---

Part 8: UIKit Complete Reference

Adding Effects

// Add indefinite effect
imageView.addSymbolEffect(.pulse)
imageView.addSymbolEffect(.breathe)
imageView.addSymbolEffect(.rotate)
imageView.addSymbolEffect(.variableColor.iterative)
imageView.addSymbolEffect(.scale.up)

// Add with options
imageView.addSymbolEffect(.bounce, options: .repeat(3))
imageView.addSymbolEffect(.pulse, options: .speed(2.0))

// Add with completion handler
imageView.addSymbolEffect(.bounce, options: .default) { context in
    // Called when effect finishes
    print("Bounce complete")
}

Removing Effects

// Remove specific effect type
imageView.removeSymbolEffect(ofType: PulseSymbolEffect.self)
imageView.removeSymbolEffect(ofType: ScaleSymbolEffect.self)
imageView.removeSymbolEffect(ofType: RotateSymbolEffect.self)

// Remove all effects
imageView.removeAllSymbolEffects()

// Remove with options
imageView.removeSymbolEffect(ofType: PulseSymbolEffect.self, options: .default)

// Remove with completion
imageView.removeSymbolEffect(ofType: PulseSymbolEffect.self) { context in
    print("Pulse removed")
}

Setting Symbol Images with Transitions

// Replace with content transition
let newImage = UIImage(systemName: "pause.fill")!
imageView.setSymbolImage(newImage, contentTransition: .replace)

// Directional replace
imageView.setSymbolImage(newImage, contentTransition: .replace.downUp)
imageView.setSymbolImage(newImage, contentTransition: .replace.upUp)
imageView.setSymbolImage(newImage, contentTransition: .replace.offUp)

// With options
imageView.setSymbolImage(newImage, contentTransition: .replace, options: .speed(2.0))

UIBarButtonItem Effects

// Effects also work on UIBarButtonItem
barButtonItem.addSymbolEffect(.bounce)
barButtonItem.addSymbolEffect(.pulse, isActive: isLoading)
barButtonItem.removeSymbolEffect(ofType: PulseSymbolEffect.self)

---

Part 9: Accessibility

Labels

// SwiftUI
Image(systemName: "star.fill")
    .accessibilityLabel("Favorite")

// UIKit
let image = UIImage(systemName: "star.fill")
imageView.accessibilityLabel = "Favorite"
imageView.isAccessibilityElement = true

// Label automatically provides accessibility
Label("Settings", systemImage: "gear")
// VoiceOver reads: "Settings"

Reduce Motion

Symbol effects automatically respect UIAccessibility.isReduceMotionEnabled. When Reduce Motion is on:

• Most effects are simplified or suppressed
• Replace transitions use crossfade instead of directional movement
• Indefinite effects may be simplified to static appearance changes

Do not attempt to override or check this yourself for effects. The system handles it. Only intervene if effects carry semantic meaning:

// If the pulsing conveys connection status, provide a text label
Image(systemName: "wifi")
    .symbolEffect(.pulse, isActive: isConnecting)
    .accessibilityLabel(isConnecting ? "Connecting to WiFi" : "WiFi connected")

Bold Text

SF Symbols automatically adapt when Bold Text is enabled in Accessibility settings. Custom symbols need weight variants to support this properly.

Dynamic Type

Symbols sized with .font() scale automatically with Dynamic Type. Symbols sized with explicit point sizes (.font(.system(size: 24))) do not scale.

// ✅ Scales with Dynamic Type
Image(systemName: "star.fill")
    .font(.title)

// ❌ Fixed size, does not scale
Image(systemName: "star.fill")
    .font(.system(size: 24))

---

Part 10: Common Patterns

Notification Badge with Effect

struct NotificationBell: View {
    let count: Int

    var body: some View {
        Image(systemName: count > 0 ? "bell.badge.fill" : "bell.fill")
            .contentTransition(.symbolEffect(.replace))
            .symbolEffect(.wiggle, value: count)
            .symbolRenderingMode(.palette)
            .foregroundStyle(count > 0 ? .red : .primary, .primary)
    }
}

WiFi Strength Indicator

struct WiFiIndicator: View {
    let strength: Double // 0.0 to 1.0
    let isSearching: Bool

    var body: some View {
        Image(systemName: "wifi", variableValue: strength)
            .symbolEffect(.variableColor.iterative, isActive: isSearching)
            .symbolRenderingMode(.hierarchical)
            .accessibilityLabel(
                isSearching ? "Searching for WiFi" :
                "WiFi strength: \(Int(strength * 100))%"
            )
    }
}

Animated Toggle

struct RecordButton: View {
    @State private var isRecording = false

    var body: some View {
        Button {
            isRecording.toggle()
        } label: {
            Image(systemName: isRecording ? "stop.circle.fill" : "record.circle")
                .contentTransition(.symbolEffect(.replace))
                .symbolEffect(.breathe.pulse, isActive: isRecording)
                .font(.largeTitle)
                .foregroundStyle(isRecording ? .red : .primary)
        }
        .accessibilityLabel(isRecording ? "Stop recording" : "Start recording")
    }
}

Multi-State Symbol with Draw (iOS 26+)

struct TaskCheckbox: View {
    @State private var isComplete = false

    var body: some View {
        Button {
            isComplete.toggle()
        } label: {
            Image(systemName: isComplete ? "checkmark.circle.fill" : "circle")
                .contentTransition(.symbolEffect(.replace))
                .symbolEffect(.drawOn, isActive: isComplete)
                .font(.title2)
                .foregroundStyle(isComplete ? .green : .secondary)
        }
        .accessibilityLabel(isComplete ? "Completed" : "Not completed")
    }
}

---

Resources

WWDC: 2023-10257, 2023-10258, 2024-10188, 2025-337

Docs: /symbols, /symbols/symboleffect, /symbols/bouncesymboleffect, /symbols/pulsesymboleffect, /symbols/variablecolorsymboleffect, /symbols/scalesymboleffect, /symbols/wigglesymboleffect, /symbols/rotatesymboleffect, /symbols/breathesymboleffect, /symbols/appearsymboleffect, /symbols/disappearsymboleffect, /symbols/replacesymboleffect, /symbols/drawonsymboleffect, /symbols/drawoffsymboleffect, /swiftui/image/symbolrenderingmode(_:), /uikit/uiimage/symbolconfiguration

Skills: axiom-sf-symbols, axiom-hig-ref, axiom-swiftui-animation-ref

---

Last Updated Based on WWDC 2023/10257-10258, WWDC 2024/10188, WWDC 2025/337 Version iOS 13+ (display), iOS 15+ (rendering modes), iOS 17+ (effects), iOS 18+ (Wiggle/Rotate/Breathe), iOS 26+ (Draw, Gradients)