Class

NSUserDefaults

An interface to the user’s defaults database, where you store key-value pairs persistently across launches of your app.

Overview

The NSUserDefaults 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 NSUserDefaults objects to read the defaults that your app uses from a user’s defaults database. NSUserDefaults 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 NSUbiquitousKeyValueStore instead.

Storing Default Objects

The NSUserDefaults 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 NSUserDefaults 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 stringForKey: 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 setObject:forKey: 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 setURL:forKey: 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 bookmarkDataWithOptions:includingResourceValuesForKeys:relativeToURL:error: method and persist it using the setObject:forKey: method. You can then use the URLByResolvingBookmarkData:options:relativeToURL:bookmarkDataIsStale:error: 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 NSUserDefaultsDidChangeNotification on the defaultCenter 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 NSUserDefaults 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 addSuiteNamed: 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.

Topics

Getting the Standard User Defaults Object

standardUserDefaults

Returns the shared defaults object.

Creating User Defaults Objects

init

Creates a user defaults object initialized with the defaults for the app and current user.

initWithSuiteName:

Creates a user defaults object initialized with the defaults for the specified database name.

Getting Default Values

objectForKey:

Returns the object associated with the specified key.

URLForKey:

Returns the URL associated with the specified key.

arrayForKey:

Returns the array associated with the specified key.

dictionaryForKey:

Returns the dictionary object associated with the specified key.

stringForKey:

Returns the string associated with the specified key.

stringArrayForKey:

Returns the array of strings associated with the specified key.

dataForKey:

Returns the data object associated with the specified key.

boolForKey:

Returns the Boolean value associated with the specified key.

integerForKey:

Returns the integer value associated with the specified key.

floatForKey:

Returns the float value associated with the specified key.

doubleForKey:

Returns the double value associated with the specified key.

dictionaryRepresentation

Returns a dictionary that contains a union of all key-value pairs in the domains in the search list.

Setting Default Values

setObject:forKey:

Sets the value of the specified default key.

setFloat:forKey:

Sets the value of the specified default key to the specified float value.

setDouble:forKey:

Sets the value of the specified default key to the double value.

setInteger:forKey:

Sets the value of the specified default key to the specified integer value.

setBool:forKey:

Sets the value of the specified default key to the specified Boolean value.

setURL:forKey:

Sets the value of the specified default key to the specified URL.

Removing Defaults

removeObjectForKey:

Removes the value of the specified default key.

Maintaining Suites

addSuiteNamed:

Inserts the specified domain name into the receiver’s search list.

removeSuiteNamed:

Removes the specified domain name from the receiver’s search list.

Registering Defaults

registerDefaults:

Adds the contents of the specified dictionary to the registration domain.

Maintaining Persistent Domains

persistentDomainForName:

Returns a dictionary representation of the defaults for the specified domain.

setPersistentDomain:forName:

Sets a dictionary for the specified persistent domain.

removePersistentDomainForName:

Removes the contents of the specified persistent domain from the user’s defaults.

persistentDomainNames

Returns an array of the current persistent domain names.

Deprecated

Maintaining Volatile Domains

volatileDomainNames

The current volatile domain names.

volatileDomainForName:

Returns the dictionary for the specified volatile domain.

setVolatileDomain:forName:

Sets the dictionary for the specified volatile domain.

removeVolatileDomainForName:

Removes the specified volatile domain from the user’s defaults.

Accessing Managed Environment Keys

objectIsForcedForKey:

Returns a Boolean value indicating whether the specified key is managed by an administrator.

objectIsForcedForKey:inDomain:

Returns a Boolean value indicating whether the key in the specified domain is managed by an administrator.

Domains

NSArgumentDomain

The domain consisting of defaults parsed from the application’s arguments. These are one or more pairs of the form -default value included in the command-line invocation of the application.

NSGlobalDomain

The domain consisting of defaults meant to be seen by all applications.

NSRegistrationDomain

The domain consisting of a set of temporary defaults whose values can be set by the application to ensure that searches will always be successful.

Notifications

NSUserDefaultsDidChangeNotification

Posted when user defaults are changed within the current process.

NSUserDefaultsSizeLimitExceededNotification

Posted when more data is stored in user defaults than is allowed.

NSUbiquitousUserDefaultsCompletedInitialSyncNotification

Posted when ubiquitous defaults finish downloading data, either the first time a device is connected to an iCloud account or when a user switches their primary iCloud account.

NSUbiquitousUserDefaultsDidChangeAccountsNotification

Posted when the user changes the primary iCloud account.

NSUbiquitousUserDefaultsNoCloudAccountNotification

Posted when a cloud default is set, but no iCloud user is logged in.

Legacy

initWithUser:

Creates a user defaults object initialized with the defaults for the specified user account.

Deprecated
synchronize

Waits for any pending asynchronous updates to the defaults database and returns; this method is unnecessary and shouldn't be used.

resetStandardUserDefaults

This method has no effect and shouldn't be used.

Language-Dependent Information Constants

These constants are deprecated and shouldn't be used.

Relationships

Inherits From