An interface to the user’s defaults database, where you store key-value pairs persistently across launches of your app.
SDKs
- iOS 2.0+
- macOS 10.0+
- Mac Catalyst 13.0+
- tvOS 9.0+
- watchOS 2.0+
Framework
- Foundation
Declaration
class UserDefaults : NSObject
Overview
The User class provides a programmatic interface for interacting with the defaults system. The defaults system allows an app to customize its behavior to match a user’s preferences. For example, you can allow users to specify their preferred units of measurement or media playback speed. Apps store these preferences by assigning values to a set of parameters in a user’s defaults database. The parameters are referred to as defaults because they’re commonly used to determine an app’s default state at startup or the way it acts by default.
At runtime, you use User objects to read the defaults that your app uses from a user’s defaults database. User caches the information to avoid having to open the user’s defaults database each time you need a default value. When you set a default value, it’s changed synchronously within your process, and asynchronously to persistent storage and other processes.
With the exception of managed devices in educational institutions, a user’s defaults are stored locally on a single device, and persisted for backup and restore. To synchronize preferences and other data across a user’s connected devices, use NSUbiquitous instead.
Storing Default Objects
The User class provides convenience methods for accessing common types such as floats, doubles, integers, Boolean values, and URLs. These methods are described in Setting Default Values.
A default object must be a property list—that is, an instance of (or for collections, a combination of instances of) NSData, NSString, NSNumber, NSDate, NSArray, or NSDictionary. If you want to store any other type of object, you should typically archive it to create an instance of NSData.
Values returned from User are immutable, even if you set a mutable object as the value. For example, if you set a mutable string as the value for “MyStringDefault”, the string you later retrieve using the string(for method will be immutable. If you set a mutable string as a default value and later mutate the string, the default value won’t reflect the mutated string value unless you call set(_: again.
For more details, see Preferences and Settings Programming Guide.
Persisting File References
A file URL specifies a location in the file system. If you use the set(_: method to store the location for a particular file and the user moves that file, your app may not be able to locate that file on next launch. To store a reference to a file by its file system identity, you can instead create NSURL bookmark data using the bookmark method and persist it using the set(_: method. You can then use the URLBy method to resolve the bookmark data stored in user defaults to a file URL.
Responding to Defaults Changes
You can use key-value observing to be notified of any updates to a particular default value. You can also register as an observer for did on the default notification center in order to be notified of all updates to a local defaults database.
For more details, see Key-Value Observing Programming Guide and Notification Programming Topics.
Using Defaults in Managed Environments
If your app supports managed environments, you can use User to determine which preferences are managed by an administrator for the benefit of the user. In a managed environment, such as a computer lab or classroom, an administrator or teacher can configure the systems by establishing a set of default preferences for users. If a preference is managed in this manner (as determined by the methods described in Accessing Managed Environment Keys), your app should prevent users from editing that preference by disabling or hiding controls.
For more details, see Mobile Device Management Protocol Reference.
An app running on a device managed by an educational institution can use the iCloud key-value store to share small amounts of data with other instances of itself on the user’s other devices. For example, a textbook app might store the current page number being read by the user so that other instances of the app can open to the same page when launched.
For more information, see Storing Preferences in iCloud in Preferences and Settings Programming Guide.
Sandbox Considerations
A sandboxed app cannot access or modify the preferences for any other app, with the following exceptions:
App extensions on macOS and iOS
Other apps in your application group on macOS
Adding a third-party app’s domain using the add method doesn’t allow your app to access to that app’s preferences. Attempting to access or modify another app’s preferences doesn’t result in an error; instead, macOS reads and writes files located within your app’s container, rather than the actual preference files for the other application.
Thread Safety
The UserDefaults class is thread-safe.