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

# NSButton

A control that defines an area on the screen that a user clicks to trigger an action.

```
class NSButton
```

## Overview

Buttons are a standard control for initiating actions within your app. You can configure buttons with many different visual styles, but the behavior is the same. When a user clicks it, a button calls the action method of its associated target object. (If you configure a button as continuous, it calls its action method at timed intervals until the user releases the mouse button or the cursor leaves the button boundaries). You use the action method to perform your app-specific tasks.

There are multiple types of buttons, each with a different user interface and behavior. The [`NSButtonCell`](/documentation/AppKit/NSButtonCell) class defines the button types, and calling the [`setButtonType(_:)`](/documentation/AppKit/NSButton/setButtonType(_:)) method configures them.

If you configure it as an accelerator button (type [`NSAcceleratorButton`](/documentation/AppKit/NSAcceleratorButton) or [`NSMultiLevelAcceleratorButton`](/documentation/AppKit/NSMultiLevelAcceleratorButton)), you can set a button to send action messages when changes in pressure occur when the user clicks the button.

Buttons can either have two states (on and off) or three states (on, off, and mixed). You enable a three-state button by calling the [`allowsMixedState`](/documentation/AppKit/NSButton/allowsMixedState) method. On and off (also referred to as alternate and normal) states indicate that the user clicked or didn’t click the button. Mixed is typically used for checkboxes or radio buttons, which allow for an additional intermediate state. For example, suppose the state of a checkbox denotes whether a text field contains bold text. If all text in the text field is bold, then the checkbox is on. If none of the text is bold, then the checkbox is off. If some of the text is bold, then the checkbox is mixed.

For most types of buttons, the value of the button matches its state—the value is `1` for on, `0` for off, or `-1` for mixed. For pressure-sensitive buttons, the value of the button indicates pressure level instead.

`NSButton` and [`NSMatrix`](/documentation/AppKit/NSMatrix) both provide a control view, which displays an `NSButtonCell` object. However, while a matrix requires you to access the button cell objects directly, most button class methods act as “covers” for identically declared button cell methods. In other words, the implementation of the button method invokes the corresponding button cell method for you, allowing you to be unconcerned with the existence of the button cell. The only button cell methods that don’t have covers relate to the font you use to display the key equivalent and to specific methods for highlighting or showing the state of the button.

## Topics

### Creating standard buttons

[`+  checkboxWithTitle:target:action:`](/documentation/AppKit/NSButton/init(checkboxWithTitle:target:action:))

Creates a standard checkbox with the title you specify.

[`+  buttonWithImage:target:action:`](/documentation/AppKit/NSButton/init(image:target:action:))

Creates a standard push button with the image you specify.

[`+  radioButtonWithTitle:target:action:`](/documentation/AppKit/NSButton/init(radioButtonWithTitle:target:action:))

Creates a standard radio button with the title you specify.

[`+  buttonWithTitle:image:target:action:`](/documentation/AppKit/NSButton/init(title:image:target:action:))

Creates a standard push button with a title and image.

[`+  buttonWithTitle:target:action:`](/documentation/AppKit/NSButton/init(title:target:action:))

Creates a standard push button with the title you specify.

### Configuring the cell

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

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

### Configuring buttons

[`-  setButtonType:`](/documentation/AppKit/NSButton/setButtonType(_:))

Sets the button’s type, which affects its user interface and behavior when clicked.

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

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

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

Sets the message delay and interval periods for a continuous button.

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

A tint color to use for the template image and text content.

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

A Boolean value that defines whether a button’s action has a destructive effect.

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

The title that the button displays when the button is in an on state.

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

The title that the button displays in an off state, as an attributed string.

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

The title that the button displays as an attributed string when the button is in an on state.

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

The title displayed on the button when it’s in an off state.

[`-  setTitleWithMnemonic:`](/documentation/AppKit/NSButton/setTitleWithMnemonic:)

Sets the title of a button with a character denoting an access key.

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

The combination of point size, weight, and scale to use when sizing and displaying symbol images.

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

The sound that plays when the user clicks the button.

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

A Boolean value that indicates whether spring loading is enabled for the button.

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

An integer value indicating the maximum pressure level for a button of type [`NSMultiLevelAcceleratorButton`](/documentation/AppKit/NSMultiLevelAcceleratorButton).

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

The tint prominence of the button. Use tint prominence to gently suggest a hierarchy when multiple buttons perform similar actions. A button with primary tint prominence suggests the most preferred option, while secondary prominence indicates a reasonable alternative. See [`NSTintProminence`](/documentation/AppKit/NSTintProminence) for a list of possible values.

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

Controls how strongly the tint color applies in a view.

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

[`BorderShape`](/documentation/AppKit/NSControl/BorderShape)

### Configuring button images

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

The image that appears on the button when it’s in an off state, or `nil` if there is no such image.

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

An alternate image that appears on the button when the button is in an on state.

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

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

[`ImagePosition`](/documentation/AppKit/NSControl/ImagePosition)

A constant for specifying the position of a button’s image relative to its title.

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

A Boolean value that determines whether the button has a border.

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

A Boolean value that indicates whether the button is transparent.

[`bezelStyle`](/documentation/AppKit/NSButton/bezelStyle-swift.property)

The appearance of the button’s border.

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

The color of the button’s bezel, in appearances that support it.

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

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

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

A Boolean value that determines how the button’s image and title are positioned together within the button bezel.

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

The scaling mode applied to make the cell’s image fit the frame of the image view.

### Managing button compression

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

The compression options active for this button.

[`-  compressWithPrioritizedCompressionOptions:`](/documentation/AppKit/NSButton/compress(withPrioritizedCompressionOptions:))

Sets the priority compression options for this button.

[`-  minimumSizeWithPrioritizedCompressionOptions:`](/documentation/AppKit/NSButton/minimumSize(withPrioritizedCompressionOptions:))

Returns the minimum size of the button by using the compression options.

### Managing button state

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

A Boolean value that indicates whether the button allows a mixed state.

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

The button’s state.

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

Sets the button to its next state.

[`-  highlight:`](/documentation/AppKit/NSButton/highlight(_:))

Highlights (or unhighlights) the button.

### Accessing key equivalents

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

The key-equivalent character of the button.

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

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

### Handling keyboard events

[`-  performKeyEquivalent:`](/documentation/AppKit/NSButton/performKeyEquivalent(with:))

Checks the button’s key equivalent against the specified event and, if they match, simulates the button being clicked.

## Relationships

### Conforms To

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### Inherits From

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

### Inherited By

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

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

---

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)