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

# NSPopUpButton

A control for selecting an item from a list.

```
class NSPopUpButton
```

## Overview

An `NSPopUpButton` object uses an [`NSPopUpButtonCell`](/documentation/AppKit/NSPopUpButtonCell) object to implement its user interface.

Note that while a menu is tracking user input, programmatic changes to the menu, such as adding, removing, or changing items on the menu, is not reflected.

> Important: Setting a pop up button’s ``doc://com.apple.appkit/documentation/AppKit/NSCell/image`` property has no effect. The image displayed in a pop up button is taken from the selected menu item (in the case of a pop up menu) or from the first menu item (in the case of a pull-down menu).

## Topics

### Initializing an NSPopUpButton

[`-  initWithFrame:pullsDown:`](/documentation/AppKit/NSPopUpButton/init(frame:pullsDown:))

Returns an `NSPopUpButton` object initialized to the specified dimensions.

### Configuring the Cell

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

The `NSPopUpButtonCell` class defines the visual appearance of pop-up buttons that display pop-up or pull-down menus. Pop-up menus present the user with a set of choices, much the way radio buttons do, but using much less space. Pull-down menus also provide a set of choices but present the information in a slightly different way, usually to provide a set of commands from which the user can choose.

### Setting the type of menu

[`pullsDown`](/documentation/AppKit/NSPopUpButton/pullsDown)

A Boolean value indicating whether the button displays a pull-down or pop-up menu.

[`autoenablesItems`](/documentation/AppKit/NSPopUpButton/autoenablesItems)

A Boolean value indicating whether the button enables and disables its items every time a user event occurs.

### Inserting and deleting items

[`-  addItemWithTitle:`](/documentation/AppKit/NSPopUpButton/addItem(withTitle:))

Adds an item with the specified title to the end of the menu.

[`-  addItemsWithTitles:`](/documentation/AppKit/NSPopUpButton/addItems(withTitles:))

Adds multiple items to the end of the menu.

[`-  insertItemWithTitle:atIndex:`](/documentation/AppKit/NSPopUpButton/insertItem(withTitle:at:))

Inserts an item at the specified position in the menu.

[`-  removeAllItems`](/documentation/AppKit/NSPopUpButton/removeAllItems())

Removes all items in the receiver’s item menu.

[`-  removeItemWithTitle:`](/documentation/AppKit/NSPopUpButton/removeItem(withTitle:))

Removes the item with the specified title from the menu.

[`-  removeItemAtIndex:`](/documentation/AppKit/NSPopUpButton/removeItem(at:))

Removes the item at the specified index.

### Getting the user’s selection

[`selectedItem`](/documentation/AppKit/NSPopUpButton/selectedItem)

The menu item that was last selected by the user.

[`titleOfSelectedItem`](/documentation/AppKit/NSPopUpButton/titleOfSelectedItem)

The title of the item that was last selected by the user.

[`indexOfSelectedItem`](/documentation/AppKit/NSPopUpButton/indexOfSelectedItem)

The index of the item that was last selected by the user.

[`selectedTag`](/documentation/AppKit/NSPopUpButton/selectedTag)

The tag of the menu item that was last selected by the user.

### Setting the current selection

[`-  selectItem:`](/documentation/AppKit/NSPopUpButton/select(_:))

Selects the specified menu item.

[`-  selectItemAtIndex:`](/documentation/AppKit/NSPopUpButton/selectItem(at:))

Selects the item in the menu at the specified index.

[`-  selectItemWithTag:`](/documentation/AppKit/NSPopUpButton/selectItem(withTag:))

Selects the menu item with the specified tag.

[`-  selectItemWithTitle:`](/documentation/AppKit/NSPopUpButton/selectItem(withTitle:))

Selects the item with the specified title.

### Getting menu items

[`menu`](/documentation/AppKit/NSPopUpButton/menu)

The menu associated with the pop-up button.

[`numberOfItems`](/documentation/AppKit/NSPopUpButton/numberOfItems)

The number of items in the menu.

[`itemArray`](/documentation/AppKit/NSPopUpButton/itemArray)

The array of menu item objects associated with the button.

[`-  itemAtIndex:`](/documentation/AppKit/NSPopUpButton/item(at:))

Returns the menu item at the specified index.

[`-  itemTitleAtIndex:`](/documentation/AppKit/NSPopUpButton/itemTitle(at:))

Returns the title of the item at the specified index.

[`itemTitles`](/documentation/AppKit/NSPopUpButton/itemTitles)

An array of strings corresponding to the titles of the items in the menu.

[`-  itemWithTitle:`](/documentation/AppKit/NSPopUpButton/item(withTitle:))

Returns the menu item with the specified title.

[`lastItem`](/documentation/AppKit/NSPopUpButton/lastItem)

The last item in the menu.

### Getting the indices of menu items

[`-  indexOfItem:`](/documentation/AppKit/NSPopUpButton/index(of:))

Returns the index of the specified menu item.

[`-  indexOfItemWithTag:`](/documentation/AppKit/NSPopUpButton/indexOfItem(withTag:))

Returns the index of the menu item with the specified tag.

[`-  indexOfItemWithTitle:`](/documentation/AppKit/NSPopUpButton/indexOfItem(withTitle:))

Returns the index of the item with the specified title.

[`-  indexOfItemWithRepresentedObject:`](/documentation/AppKit/NSPopUpButton/indexOfItem(withRepresentedObject:))

Returns the index of the menu item that holds the specified represented object.

[`-  indexOfItemWithTarget:andAction:`](/documentation/AppKit/NSPopUpButton/indexOfItem(withTarget:andAction:))

Returns the index of the menu item with the specified target and action.

### Setting the cell edge to pop out in restricted situations

[`preferredEdge`](/documentation/AppKit/NSPopUpButton/preferredEdge)

The edge of the button on which to display the menu when screen space is constrained.

### Setting the title

[`-  setTitle:`](/documentation/AppKit/NSPopUpButton/setTitle(_:))

Sets the string displayed in the receiver when the user isn’t pressing the mouse button.

### Setting the state

[`-  synchronizeTitleAndSelectedItem`](/documentation/AppKit/NSPopUpButton/synchronizeTitleAndSelectedItem())

Ensures that the item being displayed by the receiver agrees with the selected item.

### Notifications

[`NSPopUpButtonWillPopUpNotification`](/documentation/AppKit/NSPopUpButton/willPopUpNotification)

Posted when an `NSPopUpButton` object receives a mouse-down event—that is, when the user is about to select an item from the menu.

### Instance Methods

[`selectedTag()`](/documentation/AppKit/NSPopUpButton/selectedTag())

## Relationships

### Conforms To

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### Inherits From

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

---

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)