TheAnimation
A type-safe wrapper for CAAnimation that prevents setting wrong type values in iOS, tvOS, and macOS animations.
What is TheAnimation?
TheAnimation is a Swift library that wraps Apple's Core Animation (CAAnimation) framework with type safety. It prevents runtime errors by ensuring animation property values (like `fromValue` and `toValue`) match the expected types for key paths, such as `CGColor` for `backgroundColor`. This makes animation code more robust and easier to debug.
iOS, tvOS, and macOS developers using Swift who need to create animations with Core Animation and want compile-time type checking to avoid common mistakes.
Developers choose TheAnimation because it eliminates the risk of setting incorrect value types in animations—a common issue with CAAnimation's `Any?` properties—while providing a familiar API that mirrors standard Core Animation classes. It enhances code safety without sacrificing functionality.
Overview
Type-safe CAAnimation wrapper. It makes preventing to set wrong type values.
Use Cases
Best For
- Adding type safety to Core Animation code in Swift projects
- Preventing runtime crashes from mismatched animation value types
- Creating reusable animation components with compile-time checks
- Simplifying animation code maintenance in large iOS/tvOS/macOS apps
- Extending Core Animation with custom type-safe key paths
- Handling animation lifecycle events with a clean Swift API
Not Ideal For
- Projects built entirely with SwiftUI that rely on its declarative animation system
- Apps requiring dynamic, runtime-assigned animation key paths where type safety restricts flexibility
- Simple projects where adding a third-party library outweighs the benefits over vanilla Core Animation
Pros & Cons
Pros
Uses generic AnimationKeyPath types like AnimationKeyPath<CGColor> to enforce correct value assignments, preventing runtime errors from mismatched types as highlighted in the README's comparison with CABasicAnimation.
Mirrors standard CAAnimation classes such as BasicAnimation and KeyframeAnimation, reducing the learning curve for developers already experienced with Core Animation, as shown in the correspondence table.
Returns an AnimationCanceller from animate(in:) for cancellation and provides setAnimationDidStart/Stop handlers, offering better manageability than vanilla CAAnimation's key-based approach.
Supports iOS, tvOS, and macOS with a unified API, enabling code reuse across Apple platforms, as indicated by the platform badges in the README.
Cons
Inherits all constraints and quirks of Core Animation, such as performance trade-offs and platform-specific behaviors, without providing higher-level abstractions or workarounds.
Requires using animate(in:) instead of the standard layer.add(_:forKey:), which can confuse developers accustomed to native CAAnimation and adds minor integration complexity.
Adds an external library for functionality that could be implemented with careful Swift extensions, potentially increasing project bloat and maintenance concerns for minimal gains in simple cases.
Frequently Asked Questions
Related Projects
LottieAn iOS library to natively render After Effects vector animations
SpringA library to simplify iOS animations in Swift.
IBAnimatableDesign and prototype customized UI, interaction, navigation, transition and animation for App Store ready Apps in Interface Builder with IBAnimatable.
ViewAnimatorViewAnimator brings your UI to life with just one line
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.