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

# NSToolbarItemGroup

A group of subitems in a toolbar item.

```
class NSToolbarItemGroup
```

## Overview

An [`NSToolbarItemGroup`](/documentation/AppKit/NSToolbarItemGroup) represents a collection set of subitems in a toolbar that the system displays based on available space and settings that you specify. The system uses the views and labels of the subitems, but the parent’s attributes take precedence. This differs from other [`NSToolbarItem`](/documentation/AppKit/NSToolbarItem) objects because they’re attached — the user drags them together as a single item rather than separately.

If a subitem of the group has an action set on it, the group uses that action instead of its own when the user clicks or taps on that item. The system prefers the subitem’s action if it exists, otherwise it uses the group’s action.

To configure an instance of [`NSToolbarItemGroup`](/documentation/AppKit/NSToolbarItemGroup), you first create the individual toolbar subitems:

```objc
NSToolbarItem *item1 = [[NSToolbarItem alloc] initWithItemIdentifier:@"Item1"];
NSToolbarItem *item2 = [[NSToolbarItem alloc] initWithItemIdentifier:@"Item2"];
[item1 setImage:[NSImage imageNamed:@"LeftArrow"]];
[item2 setImage:[NSImage imageNamed:@"RightArrow"]];
[item1 setLabel:@"Prev"];
[item2 setLabel:@"Next"];
```

Then, you put them in a grouped item:

```objc
NSToolbarItemGroup *group = [[NSToolbarItemGroup alloc] initWithItemIdentifier:@"GroupItem"];
[group setSubitems:[NSArray arrayWithObjects:item1, item2, nil]];
```

In this configuration, you get two grouped items, and two labels.

If you set a label on the parent item, you get two grouped items with one shared label:

```objc
[group setLabel:@"Navigate"];
```

If instead you set a view on the parent item, you get two labels with one shared view:

```objc
[group setView:someSegmentedControl];
```

## Topics

### Creating grouped toolbar items

[`init(itemIdentifier:images:selectionMode:labels:target:action:)`](/documentation/AppKit/NSToolbarItemGroup/init(itemIdentifier:images:selectionMode:labels:target:action:))

Creates a grouped toolbar item with images.

[`init(itemIdentifier:titles:selectionMode:labels:target:action:)`](/documentation/AppKit/NSToolbarItemGroup/init(itemIdentifier:titles:selectionMode:labels:target:action:))

Creates a grouped toolbar item with labels.

### Working with subitems

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

The subitems of the grouped toolbar item.

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

The index value for the most recently selected subitem of a grouped toolbar item.

[`isSelected(at:)`](/documentation/AppKit/NSToolbarItemGroup/isSelected(at:))

Indicates whether a specified index is currently selected.

[`setSelected(_:at:)`](/documentation/AppKit/NSToolbarItemGroup/setSelected(_:at:))

Sets the selected state of a subitem in a grouped toolbar item.

### Configuring grouped toolbar items

[`controlRepresentation`](/documentation/AppKit/NSToolbarItemGroup/controlRepresentation-swift.property)

A value that represents how a toolbar displays a grouped toolbar item.

[`NSToolbarItemGroup.ControlRepresentation`](/documentation/AppKit/NSToolbarItemGroup/ControlRepresentation-swift.enum)

[`selectionMode`](/documentation/AppKit/NSToolbarItemGroup/selectionMode-swift.property)

The selection mode of the grouped toolbar item.

[`NSToolbarItemGroup.SelectionMode`](/documentation/AppKit/NSToolbarItemGroup/SelectionMode-swift.enum)

A value that indicates how a grouped toolbar item selects its subitems.

[`role`](/documentation/AppKit/NSToolbarItemGroup/role-swift.property)

The semantic role of the item.
Defaults to `NSToolbarItemGroupRoleAutomatic`.

[`NSToolbarItemGroup.Role`](/documentation/AppKit/NSToolbarItemGroup/Role-swift.enum)


---

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)