<!--
{
  "availability" : [
    "iOS: 17.0.0 -",
    "iPadOS: -",
    "macCatalyst: 17.0.0 -",
    "macOS: 14.0.0 -",
    "tvOS: 17.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 10.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Symbols",
  "identifier" : "/documentation/Symbols",
  "metadataVersion" : "0.1.0",
  "role" : "Framework",
  "symbol" : {
    "kind" : "Framework",
    "modules" : [
      "Symbols"
    ],
    "preciseIdentifier" : "Symbols"
  },
  "title" : "Symbols"
}
-->

# Symbols

Apply universal animations to symbol-based images.

## Overview

The Symbols framework provides access to symbol effects you can use to animate [SF Symbols](https://developer.apple.com/design/human-interface-guidelines/sf-symbols) in your AppKit, UIKit, and SwiftUI apps. These animations exhibit different behaviors:

- Discrete: An effect that runs from start to finish.
- Indefinite: An effect that lasts until you remove or disable it.
- Transition: An effect that animates a symbol in or out of visibility.
- Content Transition: An effect that replaces one symbol with another symbol, or with a different configuration of itself.

A symbol effect can exhibit multiple types of behavior. For instance, you can add a pulse effect with an option to occur a finite number of times — a discrete behavior. You can also add a pulse effect with an option to loop forever — an indefinite behavior.

```swift
// Add an effect in SwiftUI.
Image(systemName: "globe")
    // Add effect with discrete behavior to image view.
    .symbolEffect(.pulse, options: .repeat(3))

Image(systemName: "globe")
    // Add effect with indefinite behavior to image view.
    .symbolEffect(.pulse)
```

You can apply universal animation effects to symbol-based images that you display in image views. The Symbols framework provides a consistent set of effects to use regardless of your UI framework or langauge choices.

Consider a SwiftUI app that displays a variable color effect on a Wi-Fi symbol while the system searches for Wi-Fi networks.

```swift
// Add an effect in SwiftUI.
Image(systemName: "wifi")
    .symbolEffect(.variableColor.reversing)
```

Now consider an AppKit or UIKit version of the app. You can apply the same effect to animate the search for Wi-Fi networks.

```objc
// Add an effect in AppKit and UIKit.
[self.imageView
  addSymbolEffect:[[NSSymbolVariableColorEffect effect] effectWithReversing]];
```

## Topics

### Symbol effects

[`appear`](/documentation/Symbols/SymbolEffect/appear)

An animation that makes the layers of a symbol-based image appear separately or as a whole.

[`bounce`](/documentation/Symbols/SymbolEffect/bounce)

An animation that applies a transitory scaling effect, or bounce, to the layers in a symbol-based image separately or as a whole.

[`disappear`](/documentation/Symbols/SymbolEffect/disappear)

An animation that makes the layers of a symbol-based image disappear separately or as a whole.

[`pulse`](/documentation/Symbols/SymbolEffect/pulse)

An animation that fades the opacity of some or all layers in a symbol-based image.

[`scale`](/documentation/Symbols/SymbolEffect/scale)

An animation that scales the layers in a symbol-based image separately or as a whole.

[`variableColor`](/documentation/Symbols/SymbolEffect/variableColor)

An animation that replaces the opacity of variable layers in a symbol-based image in a repeatable sequence.

[`NSSymbolAppearEffect`](/documentation/Symbols/NSSymbolAppearEffect)

A type that makes the layers of a symbol-based image appear separately or as a whole.

[`NSSymbolBounceEffect`](/documentation/Symbols/NSSymbolBounceEffect)

A type that applies a transitory scaling effect, or bounce, to the layers in a symbol-based image separately or as a whole.

[`NSSymbolDisappearEffect`](/documentation/Symbols/NSSymbolDisappearEffect)

A type that makes the layers of a symbol-based image disappear separately or as a whole.

[`NSSymbolPulseEffect`](/documentation/Symbols/NSSymbolPulseEffect)

A type that fades the opacity of some or all layers in a symbol-based image.

[`NSSymbolScaleEffect`](/documentation/Symbols/NSSymbolScaleEffect)

A type that scales the layers in a symbol-based image separately or as a whole.

[`NSSymbolVariableColorEffect`](/documentation/Symbols/NSSymbolVariableColorEffect)

A type that replaces the opacity of variable layers in a symbol-based image in a repeatable sequence.

[`NSSymbolBreatheEffect`](/documentation/Symbols/NSSymbolBreatheEffect)

A symbol effect that applies the Breathe animation to
symbol images.

[`NSSymbolRotateEffect`](/documentation/Symbols/NSSymbolRotateEffect)

A symbol effect that applies the Rotate animation to
symbol images.

[`NSSymbolWiggleEffect`](/documentation/Symbols/NSSymbolWiggleEffect)

A symbol effect that applies the Wiggle animation to symbol images.

### Symbol content transitions

[`replace`](/documentation/Symbols/SymbolEffect/replace)

An animation that replaces the layers of one symbol-based image with those of another.

[`automatic`](/documentation/Symbols/SymbolEffect/automatic)

A transition that applies the default animation to a symbol-based image in a context-sensitive manner.

[`NSSymbolReplaceContentTransition`](/documentation/Symbols/NSSymbolReplaceContentTransition)

A type that replaces the layers of one symbol-based image with those of another.

[`NSSymbolAutomaticContentTransition`](/documentation/Symbols/NSSymbolAutomaticContentTransition)

A type that applies the default animation to a symbol-based image in a context-sensitive manner.

[`NSSymbolMagicReplaceContentTransition`](/documentation/Symbols/NSSymbolMagicReplaceContentTransition)

A symbol effect applies the MagicReplace animation to
symbol images.

### Symbol effect types

[`AppearSymbolEffect`](/documentation/Symbols/AppearSymbolEffect)

A type that makes the layers of a symbol-based image appear separately or as a whole.

[`AutomaticSymbolEffect`](/documentation/Symbols/AutomaticSymbolEffect)

A type that applies the default animation to a symbol-based image in a context-sensitive manner.

[`BounceSymbolEffect`](/documentation/Symbols/BounceSymbolEffect)

A type that applies a transitory scaling effect, or bounce, to the layers in a symbol-based image separately or as a whole.

[`DisappearSymbolEffect`](/documentation/Symbols/DisappearSymbolEffect)

A type that makes the layers of a symbol-based image disappear separately or as a whole.

[`PulseSymbolEffect`](/documentation/Symbols/PulseSymbolEffect)

A type that fades the opacity of some or all layers in a symbol-based image.

[`ReplaceSymbolEffect`](/documentation/Symbols/ReplaceSymbolEffect)

A type that replaces the layers of one symbol-based image with those of another.

[`ScaleSymbolEffect`](/documentation/Symbols/ScaleSymbolEffect)

A type that scales the layers in a symbol-based image separately or as a whole.

[`VariableColorSymbolEffect`](/documentation/Symbols/VariableColorSymbolEffect)

A type that replaces the opacity of variable layers in a symbol-based image in a repeatable sequence.

[`BreatheSymbolEffect`](/documentation/Symbols/BreatheSymbolEffect)

A symbol effect that applies the Breathe animation to
symbol images.

[`RotateSymbolEffect`](/documentation/Symbols/RotateSymbolEffect)

A symbol effect that applies the Rotate animation to
symbol images.

[`WiggleSymbolEffect`](/documentation/Symbols/WiggleSymbolEffect)

A symbol effect that applies the Wiggle animation to symbol images.

### Symbol effect options

[`SymbolEffectOptions`](/documentation/Symbols/SymbolEffectOptions)

Options that configure how effects apply to symbol-based images.

[`NSSymbolEffectOptions`](/documentation/Symbols/NSSymbolEffectOptions)

Options that configure how effects apply to symbol-based images.

[`NSSymbolEffectOptionsRepeatBehavior`](/documentation/Symbols/NSSymbolEffectOptionsRepeatBehavior)

The behavior of repetition to use when a symbol effect is animating.

### Symbol effect protocols

[`SymbolEffect`](/documentation/Symbols/SymbolEffect)

A presentation effect that you apply to a symbol-based image.

[`DiscreteSymbolEffect`](/documentation/Symbols/DiscreteSymbolEffect)

An effect that performs a transient animation.

[`IndefiniteSymbolEffect`](/documentation/Symbols/IndefiniteSymbolEffect)

An animation that continually affects a symbol until it’s disabled or removed.

[`ContentTransitionSymbolEffect`](/documentation/Symbols/ContentTransitionSymbolEffect)

An effect that animates between symbols or different configurations of the same symbol.

[`TransitionSymbolEffect`](/documentation/Symbols/TransitionSymbolEffect)

An effect that animates a symbol in or out.

### Symbol effect classes

[`NSSymbolEffect`](/documentation/Symbols/NSSymbolEffect)

An abstract base class for effects that you can apply to a symbol-based image.

[`NSSymbolContentTransition`](/documentation/Symbols/NSSymbolContentTransition)

An abstract base class for transitions you can apply to symbol-based images.


---

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)