<!--
{
  "availability" : [
    "iOS: 2.0.0 -",
    "iPadOS: 2.0.0 -",
    "macCatalyst: 13.1.0 -",
    "tvOS: -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "UIKit",
  "identifier" : "/documentation/UIKit/UIBarButtonItem",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "UIKit"
    ],
    "preciseIdentifier" : "c:objc(cs)UIBarButtonItem"
  },
  "title" : "UIBarButtonItem"
}
-->

# UIBarButtonItem

A specialized button for placement on a toolbar, navigation bar, or shortcuts bar.

```
@MainActor class UIBarButtonItem
```

## Overview

You typically use Interface Builder to create and configure bar button items. However, you can customize the appearance of buttons by sending the setter messages to [`UIBarButtonItemAppearance`](/documentation/UIKit/UIBarButtonItemAppearance) to customize all buttons, or to a specific [`UIBarButtonItem`](/documentation/UIKit/UIBarButtonItem) instance. You can use customized buttons in standard places in a [`UINavigationItem`](/documentation/UIKit/UINavigationItem) object or a [`UIToolbar`](/documentation/UIKit/UIToolbar) instance.

In general, specify a value for the normal state so that other states without a custom value set can use it. Similarly, when a property depends on the bar metrics (for instance, on the iPhone in landscape orientation, bars have a different height from the standard), specify a value of [`UIBarMetrics.default`](/documentation/UIKit/UIBarMetrics/default).

## Topics

### Creating items

[`init(title:image:primaryAction:menu:)`](/documentation/UIKit/UIBarButtonItem/init(title:image:primaryAction:menu:))

Creates a plain-style item using the specified title, image, primary action, and context menu.

[`init(title:image:target:action:menu:)`](/documentation/UIKit/UIBarButtonItem/init(title:image:target:action:menu:))

Creates a plain-style item using the specified title, image, target, action, and context menu.

[`initWithPrimaryAction:menu:`](/documentation/UIKit/UIBarButtonItem/initWithPrimaryAction:menu:)

Creates a plain-style item using the specified primary action and context menu.

[`initWithPrimaryAction:`](/documentation/UIKit/UIBarButtonItem/initWithPrimaryAction:)

Creates a plain-style item using the specified primary action.

[`initWithTitle:image:target:action:menu:`](/documentation/UIKit/UIBarButtonItem/initWithTitle:image:target:action:menu:)

Creates a plain-style item the specified title, image, target, action, and context menu.

[`initWithTitle:menu:`](/documentation/UIKit/UIBarButtonItem/initWithTitle:menu:)

Creates a plain-style item using the specified title and menu.

[`initWithImage:menu:`](/documentation/UIKit/UIBarButtonItem/initWithImage:menu:)

Creates a plain-style item using the specified image and context menu.

[`init()`](/documentation/UIKit/UIBarButtonItem/init())

Initializes the item to its default state.

[`init(coder:)`](/documentation/UIKit/UIBarButtonItem/init(coder:))

Creates an item from data in an unarchiver.

### Creating items of a specific style

[`init(title:style:target:action:)`](/documentation/UIKit/UIBarButtonItem/init(title:style:target:action:))

Creates an item using the specified title, style, target, and action.

[`init(image:style:target:action:)`](/documentation/UIKit/UIBarButtonItem/init(image:style:target:action:))

Creates an item using the specified image, style, target, and action.

[`init(image:landscapeImagePhone:style:target:action:)`](/documentation/UIKit/UIBarButtonItem/init(image:landscapeImagePhone:style:target:action:))

Creates an item using the specified images, style, target, and action.

### Creating system items

[`init(systemItem:primaryAction:menu:)`](/documentation/UIKit/UIBarButtonItem/init(systemItem:primaryAction:menu:))

Creates an item using the specified system item, primary action, and context menu.

[`initWithBarButtonSystemItem:primaryAction:menu:`](/documentation/UIKit/UIBarButtonItem/initWithBarButtonSystemItem:primaryAction:menu:)

Creates an item using the specified system item, primary action, and context menu.

[`initWithBarButtonSystemItem:primaryAction:`](/documentation/UIKit/UIBarButtonItem/initWithBarButtonSystemItem:primaryAction:)

Creates an item using the specified system item and primary action.

[`initWithBarButtonSystemItem:menu:`](/documentation/UIKit/UIBarButtonItem/initWithBarButtonSystemItem:menu:)

Creates an item using the specified system item and context menu.

[`init(barButtonSystemItem:target:action:)`](/documentation/UIKit/UIBarButtonItem/init(barButtonSystemItem:target:action:))

Creates an item using the specified system item, target, and action.

[`UIBarButtonItem.SystemItem`](/documentation/UIKit/UIBarButtonItem/SystemItem)

Constants that define system-supplied images for bar button items.

### Creating custom items

[`init(customView:)`](/documentation/UIKit/UIBarButtonItem/init(customView:))

Creates an item using the specified custom view.

### Creating space items

[`fixedSpace(_:)`](/documentation/UIKit/UIBarButtonItem/fixedSpace(_:))

Creates a new fixed-width space item.

[`fixedSpace()`](/documentation/UIKit/UIBarButtonItem/fixedSpace())

Creates a new fixed space item of zero width.

[`flexibleSpace()`](/documentation/UIKit/UIBarButtonItem/flexibleSpace())

Creates a new flexible-width space item.

### Creating groups

[`creatingOptionalGroup(customizationIdentifier:isInDefaultCustomization:)`](/documentation/UIKit/UIBarButtonItem/creatingOptionalGroup(customizationIdentifier:isInDefaultCustomization:))

Places the item in an optional group that a person can move, add to, or remove from the navigation bar during layout customization.

[`creatingFixedGroup()`](/documentation/UIKit/UIBarButtonItem/creatingFixedGroup())

Places the item in a fixed group that a person can’t move or remove from the navigation bar during layout customization.

[`creatingMovableGroup(customizationIdentifier:)`](/documentation/UIKit/UIBarButtonItem/creatingMovableGroup(customizationIdentifier:))

Places the item in a movable group that a person can move but can’t remove from the navigation bar during layout customization.

[`creatingOptionalGroupWithCustomizationIdentifier:inDefaultCustomization:`](/documentation/UIKit/UIBarButtonItem/creatingOptionalGroupWithCustomizationIdentifier:inDefaultCustomization:)

Places the item in an optional group that a person can move, add to, or remove from the navigation bar during layout customization.

### Managing the custom view

[`customView`](/documentation/UIKit/UIBarButtonItem/customView)

A custom view representing the item.

### Managing the action

[`primaryAction`](/documentation/UIKit/UIBarButtonItem/primaryAction)

The action associated with the item.

[`changesSelectionAsPrimaryAction`](/documentation/UIKit/UIBarButtonItem/changesSelectionAsPrimaryAction)

A Boolean value that indicates whether the button represents an action or selection.

[`action`](/documentation/UIKit/UIBarButtonItem/action)

The selector defining the action message to send to the target object when the user taps this bar button item.

[`target`](/documentation/UIKit/UIBarButtonItem/target)

The object that receives an action when the user selects the item.

### Managing the context menu

[`menu`](/documentation/UIKit/UIBarButtonItem/menu)

The context menu for this button.

[`preferredMenuElementOrder`](/documentation/UIKit/UIBarButtonItem/preferredMenuElementOrder)

The preferred menu-element ordering strategy for the menu.

### Customizing item appearance

[`style`](/documentation/UIKit/UIBarButtonItem/style-swift.property)

The style of the item.

[`UIBarButtonItem.Style`](/documentation/UIKit/UIBarButtonItem/Style-swift.enum)

Constants that specify the style of an item.

[`tintColor`](/documentation/UIKit/UIBarButtonItem/tintColor)

The tint color to apply to the button item.

[`isHidden`](/documentation/UIKit/UIBarButtonItem/isHidden)

A Boolean that determines the visibility of the item.

[`isSelected`](/documentation/UIKit/UIBarButtonItem/isSelected)

A Boolean value that indicates whether the button is in a selected state.

[`width`](/documentation/UIKit/UIBarButtonItem/width)

The width of the item.

[`possibleTitles`](/documentation/UIKit/UIBarButtonItem/possibleTitles)

The set of possible titles to display on the bar button.

### Customizing the Back button

[`backButtonBackgroundImage(for:barMetrics:)`](/documentation/UIKit/UIBarButtonItem/backButtonBackgroundImage(for:barMetrics:))

Returns the back button background image for a specified control state and bar metrics.

[`setBackButtonBackgroundImage(_:for:barMetrics:)`](/documentation/UIKit/UIBarButtonItem/setBackButtonBackgroundImage(_:for:barMetrics:))

Sets the back button background image for a specified control state and bar metrics.

[`backButtonTitlePositionAdjustment(for:)`](/documentation/UIKit/UIBarButtonItem/backButtonTitlePositionAdjustment(for:))

Returns the back button title offset for specified bar metrics.

[`setBackButtonTitlePositionAdjustment(_:for:)`](/documentation/UIKit/UIBarButtonItem/setBackButtonTitlePositionAdjustment(_:for:))

Sets the back button title offset for specified bar metrics.

[`backButtonBackgroundVerticalPositionAdjustment(for:)`](/documentation/UIKit/UIBarButtonItem/backButtonBackgroundVerticalPositionAdjustment(for:))

Returns the back button vertical position offset for specified bar metrics.

[`setBackButtonBackgroundVerticalPositionAdjustment(_:for:)`](/documentation/UIKit/UIBarButtonItem/setBackButtonBackgroundVerticalPositionAdjustment(_:for:))

Sets the back button vertical position offset for specified bar metrics.

### Customizing the background

[`backgroundVerticalPositionAdjustment(for:)`](/documentation/UIKit/UIBarButtonItem/backgroundVerticalPositionAdjustment(for:))

Returns the background vertical position offset for specified bar metrics.

[`setBackgroundVerticalPositionAdjustment(_:for:)`](/documentation/UIKit/UIBarButtonItem/setBackgroundVerticalPositionAdjustment(_:for:))

Sets the background vertical position offset for specified bar metrics.

[`backgroundImage(for:barMetrics:)`](/documentation/UIKit/UIBarButtonItem/backgroundImage(for:barMetrics:))

Returns the background image for a specified state and bar metrics.

[`setBackgroundImage(_:for:barMetrics:)`](/documentation/UIKit/UIBarButtonItem/setBackgroundImage(_:for:barMetrics:))

Sets the background image for a specified state and bar metrics.

[`backgroundImage(for:style:barMetrics:)`](/documentation/UIKit/UIBarButtonItem/backgroundImage(for:style:barMetrics:))

Returns the background image for the specified state, style, and metrics.

[`setBackgroundImage(_:for:style:barMetrics:)`](/documentation/UIKit/UIBarButtonItem/setBackgroundImage(_:for:style:barMetrics:))

Sets the background image for the specified state, style, and metrics.

### Customizing the title placement

[`titlePositionAdjustment(for:)`](/documentation/UIKit/UIBarButtonItem/titlePositionAdjustment(for:))

Returns the title offset for specified bar metrics.

[`setTitlePositionAdjustment(_:for:)`](/documentation/UIKit/UIBarButtonItem/setTitlePositionAdjustment(_:for:))

Sets the title offset for specified bar metrics.

### Configuring symbol effects

[`isSymbolAnimationEnabled`](/documentation/UIKit/UIBarButtonItem/isSymbolAnimationEnabled)

A Boolean value that indicates whether symbol effects animate.

[`addSymbolEffect(_:options:animated:)`](/documentation/UIKit/UIBarButtonItem/addSymbolEffect(_:options:animated:)-3iew0)

Adds an indefinite symbol effect to the bar button item with the specified options and animation.

[`addSymbolEffect(_:options:animated:)`](/documentation/UIKit/UIBarButtonItem/addSymbolEffect(_:options:animated:)-6jx3e)

Adds a discrete, indefinite symbol effect to the bar button item with the specified options and animation.

[`addSymbolEffect(_:options:animated:)`](/documentation/UIKit/UIBarButtonItem/addSymbolEffect(_:options:animated:)-9dytr)

Adds a discrete symbol effect to the bar button item with the specified options and animation.

[`setSymbolImage(_:contentTransition:options:)`](/documentation/UIKit/UIBarButtonItem/setSymbolImage(_:contentTransition:options:))

Sets a symbol image using the specified content-transition effect and options.

[`removeSymbolEffect(ofType:options:animated:)`](/documentation/UIKit/UIBarButtonItem/removeSymbolEffect(ofType:options:animated:)-214pl)

Removes the symbol effect that matches the specified indefinite effect type, using the specified options and animation setting.

[`removeSymbolEffect(ofType:options:animated:)`](/documentation/UIKit/UIBarButtonItem/removeSymbolEffect(ofType:options:animated:)-7m567)

Removes the symbol effect that matches the specified discrete, indefinite effect type, using the specified options and animation setting.

[`removeSymbolEffect(ofType:options:animated:)`](/documentation/UIKit/UIBarButtonItem/removeSymbolEffect(ofType:options:animated:)-8zc4d)

Removes the symbol effect that matches the specified discrete effect type, using the specified options and animation setting.

[`removeAllSymbolEffects(options:animated:)`](/documentation/UIKit/UIBarButtonItem/removeAllSymbolEffects(options:animated:))

Removes all symbol effects from the bar button item, using the specified options and animation setting.

[`addSymbolEffect:`](/documentation/UIKit/UIBarButtonItem/addSymbolEffect:)

Adds a symbol effect to the bar button item with default options and animation.

[`addSymbolEffect:options:`](/documentation/UIKit/UIBarButtonItem/addSymbolEffect:options:)

Adds a symbol effect to the bar button item with the specified options and default animation.

[`addSymbolEffect:options:animated:`](/documentation/UIKit/UIBarButtonItem/addSymbolEffect:options:animated:)

Adds a symbol effect to the bar button item with the specified options and animation.

[`setSymbolImage:withContentTransition:`](/documentation/UIKit/UIBarButtonItem/setSymbolImage:withContentTransition:)

Sets a symbol image using the specified content-transition effect.

[`setSymbolImage:withContentTransition:options:`](/documentation/UIKit/UIBarButtonItem/setSymbolImage:withContentTransition:options:)

Sets a symbol image using the specified content-transition effect and options.

[`removeSymbolEffectOfType:`](/documentation/UIKit/UIBarButtonItem/removeSymbolEffectOfType:)

Removes the symbol effect that matches the specified effect type.

[`removeSymbolEffectOfType:options:`](/documentation/UIKit/UIBarButtonItem/removeSymbolEffectOfType:options:)

Removes the symbol effect that matches the specified effect type, using the specified options.

[`removeSymbolEffectOfType:options:animated:`](/documentation/UIKit/UIBarButtonItem/removeSymbolEffectOfType:options:animated:)

Removes the symbol effect that matches the specified effect type, using the specified options and animation setting.

[`removeAllSymbolEffects`](/documentation/UIKit/UIBarButtonItem/removeAllSymbolEffects)

Removes all symbol effects from the bar button item.

[`removeAllSymbolEffectsWithOptions:`](/documentation/UIKit/UIBarButtonItem/removeAllSymbolEffectsWithOptions:)

Removes all symbol effects from the bar button item, using the specified options.

[`removeAllSymbolEffectsWithOptions:animated:`](/documentation/UIKit/UIBarButtonItem/removeAllSymbolEffectsWithOptions:animated:)

Removes all symbol effects from the bar button item, using the specified options and animation setting.

### Getting the group

[`buttonGroup`](/documentation/UIKit/UIBarButtonItem/buttonGroup)

The group that the button belongs to.

### Representing the item in a menu

[`menuRepresentation`](/documentation/UIKit/UIBarButtonItem/menuRepresentation)

A menu element that represents the item when it appears in a menu.

### Adding a badge

[`badge`](/documentation/UIKit/UIBarButtonItem/badge-4sz3f)

[`badge`](/documentation/UIKit/UIBarButtonItem/badge-1zzen)

Sets a badge on the bar button item. Supported in navigation bars and toolbars.

[`UIBarButtonItem.Badge`](/documentation/UIKit/UIBarButtonItem/Badge-swift.struct)

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

A badge to be rendered on a bar button item.

### Customizing placement in a toolbar

[`hidesSharedBackground`](/documentation/UIKit/UIBarButtonItem/hidesSharedBackground)

A boolean value indicating whether the background this item may share with other items in the bar
should be hidden.

[`sharesBackground`](/documentation/UIKit/UIBarButtonItem/sharesBackground)

A boolean value indicating whether this bar button item can share a background with other items
in a navigation bar or a toolbar.


---

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)