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

# NSToolbarItem

A single item that appears in a window’s toolbar.

```
@MainActor class NSToolbarItem
```

## Overview

An [`NSToolbarItem`](/documentation/AppKit/NSToolbarItem) object displays an image and text string in the toolbar area of a window. You can also create toolbar items that display custom views you provide. Toolbar items provide fast access to common commands or features in the window. For example, the Finder window uses toolbar items to help someone navigate the file system.

You typically create toolbar items at the same time you create your window’s toolbar. The system provides some standard items like spacers you can include in your toolbar. It also provides items that display standard interfaces like the color panel or font panel. For any custom toolbar items you create, provide an action method to call when someone clicks the item.

You can display your toolbar item’s content using a custom view if you prefer, rather than an image and text label. If you specify an [`NSSearchField`](/documentation/AppKit/NSSearchField) object for the view, the system automatically adjusts the minimum and maximum size of the search field to the system-standard values.

## Topics

### Creating a toolbar item

[`-  initWithItemIdentifier:`](/documentation/AppKit/NSToolbarItem/init(itemIdentifier:))

Creates a toolbar item with the specified identifier.

[`+  itemWithItemIdentifier:barButtonItem:`](/documentation/AppKit/NSToolbarItem/init(itemIdentifier:barButtonItem:))

Creates a toolbar item with property values from the specified bar button item.

### Getting the toolbar item’s identity

[`itemIdentifier`](/documentation/AppKit/NSToolbarItem/itemIdentifier)

The value you use to identify the toolbar item.

[`Identifier`](/documentation/AppKit/NSToolbarItem/Identifier)

Constants for the standard toolbar items that the system provides.

### Describing the item

[`possibleLabels`](/documentation/AppKit/NSToolbarItem/possibleLabels)

The set of labels that the item might display.

[`label`](/documentation/AppKit/NSToolbarItem/label)

The label that appears for this item in the toolbar.

[`paletteLabel`](/documentation/AppKit/NSToolbarItem/paletteLabel)

The label that appears when the toolbar item is in the customization palette.

[`title`](/documentation/AppKit/NSToolbarItem/title)

The title of the toolbar item.

[`toolTip`](/documentation/AppKit/NSToolbarItem/toolTip)

The tooltip to display when someone hovers over the item in the toolbar.

### Getting the item’s visual appearance

[`image`](/documentation/AppKit/NSToolbarItem/image)

The image to display for the toolbar item.

[`backgroundTintColor`](/documentation/AppKit/NSToolbarItem/backgroundTintColor)

[`view`](/documentation/AppKit/NSToolbarItem/view)

The custom view you use to draw the toolbar item.

### Performing the item’s action

[`target`](/documentation/AppKit/NSToolbarItem/target)

The object that defines the action method the toolbar item calls when clicked.

[`action`](/documentation/AppKit/NSToolbarItem/action)

The action method to call when someone clicks on the toolbar item.

### Configuring the item’s menu

[`menuFormRepresentation`](/documentation/AppKit/NSToolbarItem/menuFormRepresentation)

The menu item to use when the toolbar item is in the overflow menu.

[`itemMenuFormRepresentation`](/documentation/AppKit/NSToolbarItem/itemMenuFormRepresentation)

The menu item to use for the toolbar item is in the overflow menu in a Mac app built with Mac Catalyst.

### Getting the item’s configuration

[`visible`](/documentation/AppKit/NSToolbarItem/isVisible)

A Boolean value that indicates whether the item is currently visible in the toolbar, and not in the overflow menu.

[`hidden`](/documentation/AppKit/NSToolbarItem/isHidden)

Determines whether an item is visible in the toolbar.

[`bordered`](/documentation/AppKit/NSToolbarItem/isBordered)

A Boolean value that indicates whether the toolbar item has a bordered style.

[`navigational`](/documentation/AppKit/NSToolbarItem/isNavigational)

A Boolean value that indicates whether the item behaves as a navigation item in the toolbar.

[`enabled`](/documentation/AppKit/NSToolbarItem/isEnabled)

A Boolean value that indicates whether the item is enabled.

[`badge`](/documentation/AppKit/NSToolbarItem/badge-17r3r)

A badge that can be attached to an NSToolbarItem. This provides a way to display small visual indicators that can be used to highlight important information, such as unread notifications or status indicators.

[`NSItemBadge`](/documentation/AppKit/NSItemBadge-swift.struct)

`NSItemBadge` represents a badge that can be attached to an `NSToolbarItem`.

[`badge`](/documentation/AppKit/NSToolbarItem/badge-2b38p)

A badge that can be attached to an NSToolbarItem. This provides a way to display small visual indicators that can be used to highlight important information, such as unread notifications or status indicators.

[`NSItemBadge`](/documentation/AppKit/NSItemBadge-c.class)

`NSItemBadge` represents a badge that can be attached to an `NSToolbarItem`.

[`style`](/documentation/AppKit/NSToolbarItem/style-swift.property)

Defines the toolbar item’s appearance. The default style is plain.
Prominent style tints the background. If a background tint color is set, it uses it; otherwise, it uses the app’s or system’s accent color. If grouped with other items,
it moves to its own to avoid tinting other items’ background.

[`Style`](/documentation/AppKit/NSToolbarItem/Style-swift.enum)

[`visibilityPriority`](/documentation/AppKit/NSToolbarItem/visibilityPriority-swift.property)

The display priority associated with the toolbar item.

[`VisibilityPriority`](/documentation/AppKit/NSToolbarItem/VisibilityPriority-swift.struct)

Constants that indicate which toolbar items to keep in the toolbar when space is limited.

[`tag`](/documentation/AppKit/NSToolbarItem/tag)

An integer tag you can use to identify the toolbar item.

### Getting the parent toolbar

[`toolbar`](/documentation/AppKit/NSToolbarItem/toolbar)

The toolbar that currently includes the item.

### Validating the item

[`autovalidates`](/documentation/AppKit/NSToolbarItem/autovalidates)

A Boolean value that indicates whether the toolbar automatically validates the item.

[`-  validate`](/documentation/AppKit/NSToolbarItem/validate())

Validates the toolbar item’s menu and its ability to perfrom its action.

### Deprecated

[`allowsDuplicatesInToolbar`](/documentation/AppKit/NSToolbarItem/allowsDuplicatesInToolbar)

A Boolean value that indicates whether the toolbar item can appear more than once in a toolbar.

[`minSize`](/documentation/AppKit/NSToolbarItem/minSize)

The toolbar item’s minimum size.

[`maxSize`](/documentation/AppKit/NSToolbarItem/maxSize)

The toolbar item’s maximum size.

## Relationships

### Conforms To

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

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

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

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

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

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

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

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

[`UIPopoverPresentationControllerSourceItem`](/documentation/UIKit/UIPopoverPresentationControllerSourceItem)

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

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

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

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

### Inherited By

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

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

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

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

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

### Inherits From

[`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class)

---

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)