How do I store a custom enum in UserDefaults with Defaults?

Ensure your enum conforms to Codable, then define a Defaults.Key with that enum type. Defaults will automatically serialize and deserialize it using JSON, as shown in the documentation examples.

Defaults vs @AppStorage: which should I use for SwiftUI?

Defaults offers stronger typing, observation, and support for Codable types, making it better for complex or type-safe needs. @AppStorage is built-in and simpler for basic use cases, but lacks these advanced features.

How to observe Defaults changes in a UIKit app?

Use the observe method on a Defaults.Key to register a callback for value changes. This avoids NotificationCenter boilerplate and works seamlessly outside SwiftUI, as detailed in the library's documentation.

Does Defaults iCloud sync work with all data types?

It relies on UserDefaults' iCloud capabilities, so keys must be marked for syncing and data types need to be compatible with NSSecureCoding or Codable. Complex custom types might require additional handling.

What's the performance cost of using Defaults?

Defaults adds JSON serialization overhead, which can impact performance for large or frequently written data. However, for typical user preferences, the trade-off is minimal compared to the type safety benefits.

Can I migrate from raw UserDefaults to Defaults easily?

Yes, by defining new Defaults.Keys with matching identifiers and default values, then gradually replacing old access points. The library maintains compatibility with underlying UserDefaults, easing migration.

Defaults — Type-Safe UserDefaults Wrapper for Swift

What is Defaults?

Defaults is a Swift library that wraps Apple's UserDefaults API with a type-safe, modern interface. It solves the problem of verbose and error-prone UserDefaults usage by allowing developers to declare strongly-typed keys with default values upfront. The library adds features like SwiftUI property wrappers, observation, and support for Codable types, making persistent storage simpler and more robust.

Target Audience

Swift developers building iOS, macOS, tvOS, watchOS, or visionOS apps who need a better way to handle persistent user preferences and app state. It's especially useful for developers using SwiftUI who want reactive updates when UserDefaults values change.

Value Proposition

Developers choose Defaults because it eliminates the stringly-typed nature of raw UserDefaults, reduces boilerplate, and provides a seamless SwiftUI experience. Its production-ready reliability, extensive type support, and iCloud synchronization offer a comprehensive solution that goes beyond Apple's built-in @AppStorage property wrapper.

💾 Swifty and modern UserDefaults

Use Cases

Best For

Storing user preferences in a type-safe way across app launches
SwiftUI apps that need reactive updates when settings change
Syncing simple app state between devices via iCloud
Replacing verbose UserDefaults code with a clean, declarative API
Storing Codable enums or custom types in UserDefaults
Observing specific UserDefaults keys for changes without NotificationCenter boilerplate

Not Ideal For

Apps targeting iOS 13 or earlier, as Defaults requires iOS 14+ and similar modern OS versions
Projects where minimizing third-party dependencies is critical, since Defaults adds an external library instead of using built-in solutions
Use cases involving large, structured datasets requiring complex queries or transactions, as UserDefaults is designed for simple key-value storage
Teams exclusively using @AppStorage for basic SwiftUI needs who don't require additional features like observation or Codable support

Pros & Cons

Pros

Compile-Time Type Safety

Declares types and default values upfront using strongly-typed keys, eliminating stringly-typed errors and ensuring safety at compile time, as emphasized in the README.

SwiftUI Reactivity

Provides a @Default property wrapper that automatically updates views when UserDefaults values change, seamlessly integrating with SwiftUI's state management for reactive UIs.

Broad Codable Support

Supports storage of any Codable value, including enums and custom types, with built-in serialization, reducing boilerplate compared to manual UserDefaults handling.

Built-in Observation

Enables easy observation of key changes without NotificationCenter boilerplate, facilitating reactive programming patterns in both SwiftUI and non-SwiftUI contexts.

Cons

Legacy OS Exclusion

Only compatible with macOS 11+, iOS 14+, and newer, which excludes apps that need to support older operating systems and devices.

Initial Setup Overhead

Requires defining keys in a Defaults.Keys extension, adding boilerplate code that might be unnecessary for very simple storage needs compared to raw UserDefaults.

Third-Party Dependency Risk

Introduces an external library that must be maintained and updated, whereas Apple's @AppStorage is built-in and less prone to breaking changes or compatibility issues.

Frequently Asked Questions

What is Defaults?

Target Audience

Value Proposition

Use Cases

Best For

Storing user preferences in a type-safe way across app launches
SwiftUI apps that need reactive updates when settings change
Syncing simple app state between devices via iCloud
Replacing verbose UserDefaults code with a clean, declarative API
Storing Codable enums or custom types in UserDefaults
Observing specific UserDefaults keys for changes without NotificationCenter boilerplate

Not Ideal For

Apps targeting iOS 13 or earlier, as Defaults requires iOS 14+ and similar modern OS versions
Projects where minimizing third-party dependencies is critical, since Defaults adds an external library instead of using built-in solutions
Use cases involving large, structured datasets requiring complex queries or transactions, as UserDefaults is designed for simple key-value storage
Teams exclusively using @AppStorage for basic SwiftUI needs who don't require additional features like observation or Codable support

Pros & Cons

Pros

Compile-Time Type Safety

Declares types and default values upfront using strongly-typed keys, eliminating stringly-typed errors and ensuring safety at compile time, as emphasized in the README.

SwiftUI Reactivity

Provides a @Default property wrapper that automatically updates views when UserDefaults values change, seamlessly integrating with SwiftUI's state management for reactive UIs.

Broad Codable Support

Supports storage of any Codable value, including enums and custom types, with built-in serialization, reducing boilerplate compared to manual UserDefaults handling.

Built-in Observation

Enables easy observation of key changes without NotificationCenter boilerplate, facilitating reactive programming patterns in both SwiftUI and non-SwiftUI contexts.

Cons

Legacy OS Exclusion

Only compatible with macOS 11+, iOS 14+, and newer, which excludes apps that need to support older operating systems and devices.

Initial Setup Overhead

Requires defining keys in a Defaults.Keys extension, adding boilerplate code that might be unnecessary for very simple storage needs compared to raw UserDefaults.

Third-Party Dependency Risk

Introduces an external library that must be maintained and updated, whereas Apple's @AppStorage is built-in and less prone to breaking changes or compatibility issues.

Frequently Asked Questions

Defaults

What is Defaults?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

Defaults

What is Defaults?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?