<!--
{
  "availability" : [
    "macOS: 10.5.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "AppKit",
  "identifier" : "/documentation/AppKit/NSDictionaryController",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "AppKit"
    ],
    "preciseIdentifier" : "c:objc(cs)NSDictionaryController"
  },
  "title" : "NSDictionaryController"
}
-->

# NSDictionaryController

A bindings-compatible controller that manages the display and editing of a dictionary of key-value pairs.

```
class NSDictionaryController
```

## Overview

[`NSDictionaryController`](/documentation/AppKit/NSDictionaryController) transforms the contents of a dictionary into an array of key-value pairs that can be bound to user interface items such as the columns of an [`NSTableView`](/documentation/AppKit/NSTableView).

The content of an [`NSDictionaryController`](/documentation/AppKit/NSDictionaryController) instance is specified using the inherited method [`content`](/documentation/AppKit/NSObjectController/content) or by binding an <doc://com.apple.documentation/documentation/Foundation/NSDictionary> instance to the [`contentDictionary`](/documentation/AppKit/NSBindingName/contentDictionary) binding. New key/value pairs inserted into the dictionary are created using the [`newObject()`](/documentation/AppKit/NSDictionaryController/newObject()) method. The initial key name is set to the string returned by [`initialKey`](/documentation/AppKit/NSDictionaryController/initialKey) . The initial key name is copied to the newly inserted object, while the object returned by [`initialValue`](/documentation/AppKit/NSDictionaryController/initialValue) is simply retained. As new items are inserted the controller enumerates the initial key name, resulting in key names such as “key”, “key1”, “key2”, and so on. This behavior can be customized by overriding [`newObject()`](/documentation/AppKit/NSDictionaryController/newObject()).

An [`NSDictionaryController`](/documentation/AppKit/NSDictionaryController) instance can be configured to exclude specified keys in a dictionary from being returned by [`arrangedObjects`](/documentation/AppKit/NSArrayController/arrangedObjects) using the [`excludedKeys`](/documentation/AppKit/NSDictionaryController/excludedKeys) property. Similarly, you can specify an array of key names that are always included in the arranged objects, even if they are not present in the content dictionary, using the [`includedKeys`](/documentation/AppKit/NSDictionaryController/includedKeys) property.

[`NSDictionaryController`](/documentation/AppKit/NSDictionaryController) supports providing localized key names for the keys in the dictionary, allowing a user-friendly representation of the key name to be displayed. The localized key names are specified by a dictionary (using [`localizedKeyDictionary`](/documentation/AppKit/NSDictionaryController/localizedKeyDictionary)) or by providing a strings table (using [`localizedKeyDictionary`](/documentation/AppKit/NSDictionaryController/localizedKeyDictionary)).

The [`arrangedObjects`](/documentation/AppKit/NSArrayController/arrangedObjects) method returns an array of objects that implement the [`NSDictionaryControllerKeyValuePair`](/documentation/AppKit/NSDictionaryControllerKeyValuePair) informal protocol. User interface controls are bound to the arranged objects array using key paths such as: `arrangedObjects.key` (displays the key name), `arrangedObjects.value` (displays the value for the key), or `arrangedObjects.localizedKey` (displays the localized key name). See [`NSDictionaryControllerKeyValuePair`](/documentation/AppKit/NSDictionaryControllerKeyValuePair) for more information.

> Note:
> You must enable the “Validates Immediately” option for the value binding of all controls that edit the key names or values returned by ``doc://com.apple.appkit/documentation/AppKit/NSArrayController/arrangedObjects``.

[`NSDictionaryController`](/documentation/AppKit/NSDictionaryController) overrides [`arrangedObjects`](/documentation/AppKit/NSArrayController/arrangedObjects) to return an array of objects that implement the [`NSDictionaryControllerKeyValuePair`](/documentation/AppKit/NSDictionaryControllerKeyValuePair) informal protocol. For more information, see [`NSDictionaryControllerKeyValuePair`](/documentation/AppKit/NSDictionaryControllerKeyValuePair).

The constants listed below are used to specify a binding to <doc://com.apple.documentation/documentation/ObjectiveC/NSObject-swift.class/bind(_:to:withKeyPath:options:)>, <doc://com.apple.documentation/documentation/ObjectiveC/NSObject-swift.class/infoForBinding(_:)>, <doc://com.apple.documentation/documentation/ObjectiveC/NSObject-swift.class/unbind(_:)>, and <doc://com.apple.documentation/documentation/ObjectiveC/NSObject-swift.class/valueClassForBinding(_:)>. For more information, see [Cocoa Bindings](/documentation/AppKit/cocoa-bindings).

- [`contentDictionary`](/documentation/AppKit/NSBindingName/contentDictionary)
- [`includedKeys`](/documentation/AppKit/NSBindingName/includedKeys)
- [`excludedKeys`](/documentation/AppKit/NSBindingName/excludedKeys)
- [`localizedKeyDictionary`](/documentation/AppKit/NSBindingName/localizedKeyDictionary)
- [`initialKey`](/documentation/AppKit/NSBindingName/initialKey)
- [`initialValue`](/documentation/AppKit/NSBindingName/initialValue)

## Topics

### Arranging Objects

[`arrangedObjects`](/documentation/AppKit/NSArrayController/arrangedObjects)

An array containing the receiver’s content objects arranged using [`arrange(_:)`](/documentation/AppKit/NSArrayController/arrange(_:)).

### Creating New Entries

[`-  newObject`](/documentation/AppKit/NSDictionaryController/newObject())

Creates and returns a new key-value pair to represent an entry in the content dictionary.

### Localizing Key Names

[`localizedKeyDictionary`](/documentation/AppKit/NSDictionaryController/localizedKeyDictionary)

The localized key names that are displayed by the receiver in place of the key names.

[`localizedKeyTable`](/documentation/AppKit/NSDictionaryController/localizedKeyTable)

the strings file used to localize key names.

### Keys to Display

[`includedKeys`](/documentation/AppKit/NSDictionaryController/includedKeys)

The key names that are represented by a key-value pair, even if they are not present in the receiver’s content dictionary.

[`excludedKeys`](/documentation/AppKit/NSDictionaryController/excludedKeys)

The key names that are never displayed in the user interface items bound to the receiver.

### Setting Initial Key and Values

[`initialKey`](/documentation/AppKit/NSDictionaryController/initialKey)

The string used as the initial key name for a newly inserted item.

[`initialValue`](/documentation/AppKit/NSDictionaryController/initialValue)

The string used as the initial value for a newly inserted item.

## Relationships

### Conforms To

[`NSEditorRegistration`](/documentation/AppKit/NSEditorRegistration)

[`Sendable`](/documentation/Swift/Sendable)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`Equatable`](/documentation/Swift/Equatable)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`Hashable`](/documentation/Swift/Hashable)

[`SendableMetatype`](/documentation/Swift/SendableMetatype)

[`NSEditor`](/documentation/AppKit/NSEditor)

[`CVarArg`](/documentation/Swift/CVarArg)

[`NSCoding`](/documentation/Foundation/NSCoding)

### Inherits From

[`NSArrayController`](/documentation/AppKit/NSArrayController)

---

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)