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

# NSButtonCell

An object that defines the user interface of a button or other clickable region of a view.

```
class NSButtonCell
```

## Overview

Setting the integer, float, double, or object value of an `NSButtonCell` object results in a call to [`state`](/documentation/AppKit/NSCell/state) with the value converted to integer. In the case of [`objectValue`](/documentation/AppKit/NSCell/objectValue), `nil` is equivalent to `0`, and a non-`nil` object that doesn’t respond to [`intValue`](/documentation/AppKit/NSCell/intValue) sets the state to `1`. Otherwise, the state is set to the object’s [`intValue`](/documentation/AppKit/NSCell/intValue). Similarly, for most button types, querying the integer, float, double, or object value of an `NSButtonCell` returns the current state in the requested representation. In the case of [`objectValue`](/documentation/AppKit/NSCell/objectValue), this is an `NSNumber` containing <doc://com.apple.documentation/documentation/Swift/true> for on, <doc://com.apple.documentation/documentation/Swift/false> for off, and integer value `-1` for the mixed state. For accelerator buttons (type [`NSAcceleratorButton`](/documentation/AppKit/NSAcceleratorButton) or [`NSMultiLevelAcceleratorButton`](/documentation/AppKit/NSMultiLevelAcceleratorButton)) on systems that support pressure sensitivity, querying [`doubleValue`](/documentation/AppKit/NSControl/doubleValue) returns the amount of pressure applied while pressing the button.

The configuration of an [`NSButtonCell`](/documentation/AppKit/NSButtonCell) object controls how the button object appears and behaves, but it’s [`NSButton`](/documentation/AppKit/NSButton) that sends a message when the control is clicked. For more information on the behavior of [`NSButtonCell`](/documentation/AppKit/NSButtonCell), see the [`NSButton`](/documentation/AppKit/NSButton) and [`NSMatrix`](/documentation/AppKit/NSMatrix) class specifications.

### Exceptions

In its implementation of the [`compare(_:)`](/documentation/AppKit/NSCell/compare(_:)) method (declared in `NSCell`), `NSButtonCell` raises an `NSBadComparisonException` if the `otherCell` argument is not of the `NSButtonCell` class.

### Fonts

Setting the [`font`](/documentation/AppKit/NSCell/font) property does nothing if the button has no title or alternate title. If the button cell has a key equivalent, its font is not changed, but the key equivalent’s font size is changed to match the new title font.

## Topics

### Creating the Cell

[`init(coder:)`](/documentation/AppKit/NSButtonCell/init(coder:))

[`init(imageCell:)`](/documentation/AppKit/NSButtonCell/init(imageCell:))

[`init(textCell:)`](/documentation/AppKit/NSButtonCell/init(textCell:))

### Setting Titles

[`alternateMnemonic`](/documentation/AppKit/NSButtonCell/alternateMnemonic)

Returns the character in the alternate title that’s marked as the “keyboard mnemonic.”

[`alternateMnemonicLocation`](/documentation/AppKit/NSButtonCell/alternateMnemonicLocation)

Returns an unsigned integer indicating the character in the alternate title that’s marked as the “keyboard mnemonic.”

[`alternateTitle`](/documentation/AppKit/NSButtonCell/alternateTitle)

The string displayed by the button when it’s in its alternate state.

[`attributedAlternateTitle`](/documentation/AppKit/NSButtonCell/attributedAlternateTitle)

The title displayed by the button when it’s in its alternate state, as an attributed string.

[`attributedTitle`](/documentation/AppKit/NSButtonCell/attributedTitle)

The title displayed by the button when it’s in its normal state as an attributed string.

[`setAlternateMnemonicLocation:`](/documentation/AppKit/NSButtonCell/setAlternateMnemonicLocation:)

Sets the character in the alternate title that should be the “keyboard mnemonic.”

[`setAlternateTitleWithMnemonic:`](/documentation/AppKit/NSButtonCell/setAlternateTitleWithMnemonic:)

Sets the title the button displays when it’s in its alternate state to the given string with an embedded mnemonic.

[`setTitleWithMnemonic:`](/documentation/AppKit/NSButtonCell/setTitleWithMnemonic:)

Sets the title the button displays when it’s in its normal state to the given string with an embedded mnemonic.

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

The title displayed on the button when it’s in its normal state.

### Managing Images

[`alternateImage`](/documentation/AppKit/NSButtonCell/alternateImage)

The image the button displays in its alternate state.

[`imagePosition`](/documentation/AppKit/NSButtonCell/imagePosition)

The position of the button’s image relative to its title.

[`imageScaling`](/documentation/AppKit/NSButtonCell/imageScaling)

The scale factor for the button’s image.

### Managing the Repeat Interval

[`getPeriodicDelay(_:interval:)`](/documentation/AppKit/NSButtonCell/getPeriodicDelay(_:interval:))

Returns by reference the delay and interval periods for a continuous button.

[`setPeriodicDelay(_:interval:)`](/documentation/AppKit/NSButtonCell/setPeriodicDelay(_:interval:))

Sets the message delay and interval for the button.

### Managing the Key Equivalent

[`keyEquivalent`](/documentation/AppKit/NSButtonCell/keyEquivalent)

The button’s key-equivalent character.

[`keyEquivalentFont`](/documentation/AppKit/NSButtonCell/keyEquivalentFont)

The font used to draw the button’s key equivalent.

[`keyEquivalentModifierMask`](/documentation/AppKit/NSButtonCell/keyEquivalentModifierMask)

The mask that identifies the modifier keys for the button’s key equivalent.

[`setKeyEquivalentFont(_:size:)`](/documentation/AppKit/NSButtonCell/setKeyEquivalentFont(_:size:))

Sets by name and size of the font used to draw the key equivalent.

### Managing Graphics Attributes

[`backgroundColor`](/documentation/AppKit/NSButtonCell/backgroundColor)

The background color of the button.

[`bezelStyle`](/documentation/AppKit/NSButtonCell/bezelStyle)

The appearance of the button’s border, if it has one.

[`gradientType`](/documentation/AppKit/NSButtonCell/gradientType)

The gradient of the button’s border.

[`imageDimsWhenDisabled`](/documentation/AppKit/NSButtonCell/imageDimsWhenDisabled)

A Boolean value that indicates if the button’s image and text appear “dim” when the button is disabled.

[`isOpaque`](/documentation/AppKit/NSButtonCell/isOpaque)

A Boolean value that indicates if the button is opaque.

[`isTransparent`](/documentation/AppKit/NSButtonCell/isTransparent)

A Boolean value that indicates if the button is transparent.

[`showsBorderOnlyWhileMouseInside`](/documentation/AppKit/NSButtonCell/showsBorderOnlyWhileMouseInside)

A Boolean value that indicates if the button displays its border only when the pointer is over it.

### Displaying the Cell

[`highlightsBy`](/documentation/AppKit/NSButtonCell/highlightsBy)

A set of flags that indicate how the button highlights when it receives a mouse-down event (that is, when the button is pressed).

[`setButtonType(_:)`](/documentation/AppKit/NSButtonCell/setButtonType(_:))

Sets how the button highlights while pressed and how it shows its state.

[`showsStateBy`](/documentation/AppKit/NSButtonCell/showsStateBy)

The flags that indicate how the button cell shows its alternate state.

### Managing the Sound

[`sound`](/documentation/AppKit/NSButtonCell/sound)

The sound that’s played when the user presses the button (that is during a mouse-down event).

### Handling Events and Action Messages

[`mouseEntered(with:)`](/documentation/AppKit/NSButtonCell/mouseEntered(with:))

Draws the button’s border.

[`mouseExited(with:)`](/documentation/AppKit/NSButtonCell/mouseExited(with:))

Erases the button’s border.

[`performClick(_:)`](/documentation/AppKit/NSButtonCell/performClick(_:))

Simulates the user clicking the button with the pointer.

### Drawing the Button Content

[`drawBezel(withFrame:in:)`](/documentation/AppKit/NSButtonCell/drawBezel(withFrame:in:))

Draws the border of the button using the current bezel style.

[`drawImage(_:withFrame:in:)`](/documentation/AppKit/NSButtonCell/drawImage(_:withFrame:in:))

Draws the image associated with the button’s current state.

[`drawTitle(_:withFrame:in:)`](/documentation/AppKit/NSButtonCell/drawTitle(_:withFrame:in:))

Draws the button’s title centered vertically in a specified rectangle.

### Constants

[`NSButton.BezelStyle`](/documentation/AppKit/NSButton/BezelStyle-swift.enum)

The set of bezel styles to style buttons in your app.

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

Button types that you can specify using [`setButtonType(_:)`](/documentation/AppKit/NSButtonCell/setButtonType(_:)).

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

Specify the gradients used by the [`gradientType`](/documentation/AppKit/NSButtonCell/gradientType) property.


---

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)