--- title: UIButton framework: uikit role: symbol role_heading: Class path: uikit/uibutton --- # UIButton A control that executes your custom code in response to user interactions. ## Declaration ```swift @MainActor class UIButton ``` ## Mentioned in Choosing a user interface idiom for your Mac app About app development with UIKit Adding user-focusable elements to a tvOS app Attaching gesture recognizers to UIKit controls Supporting VoiceOver in your app ## Overview Overview When you tap a button, or select a button that has focus, the button performs any actions attached to it. You communicate the purpose of a button using a text label, an image, or both. The appearance of buttons is configurable, so you can tint buttons or format titles to match the design of your app. You can add buttons to your interface programmatically or using Interface Builder. When adding a button to your interface, perform the following steps: Set the type of the button at creation time. Supply a title string or image; size the button appropriately for your content. Connect one or more action methods to the button. Set up Auto Layout rules to govern the size and position of the button in your interface. Provide accessibility information and localized strings. important: An app built with Mac Catalyst running in macOS 11 throws an exception when calling a button’s addGestureRecognizer(_:) method when buttonType is UIButton.ButtonType.system and the user interface idiom is UIUserInterfaceIdiom.mac. Respond to button taps Buttons use the target-action design pattern to notify your app when the user taps the button. Rather than handle touch events directly, you assign action methods to the button and designate which events trigger calls to your methods. At runtime, the button handles all incoming touch events and calls your methods in response. You connect a button to your action method using the addTarget(_:action:for:) method or by creating a connection in Interface Builder. The signature of an action method takes one of three forms, as shown in the following code. Choose the form that provides the information that you need to respond to the button tap. Configure a button’s appearance A button’s type defines its basic appearance and behavior. You specify the type of a button at creation time using the init(type:) method or in your storyboard file. After creating a button, you can’t change its type. The most commonly used button types are the Custom and System types, but use the other types when appropriate. note: To configure the appearance of all buttons in your app, use the appearance proxy object. The UIButton class implements the appearance() class method, which you can use to fetch the appearance proxy for all buttons in your app. Configure button states Buttons have five states that define their appearance: default, highlighted, focused, selected, and disabled. When you add a button to your interface, it’s in the default state initially, which means the button is enabled and the user isn’t interacting with it. As the user interacts with the button, its state changes to the other values. For example, when the user taps a button with a title, the button moves to the highlighted state. When configuring a button either programmatically or in Interface Builder, you specify attributes for each state separately. In Interface Builder, use the State Config control in the Attributes inspector to choose the appropriate state and then configure the other attributes. If you don’t specify attributes for a particular state, the UIButton class provides a reasonable default behavior. For example, a disabled button is normally dimmed and doesn’t display a highlight when tapped. Other properties of this class, such as the adjustsImageWhenHighlighted and adjustsImageWhenDisabled properties, let you alter the default behavior in specific cases. Provide content The content of a button consists of a title string or image that you specify. The content you specify is used to configure the UILabel and UIImageView object managed by the button itself. You can access these objects using the titleLabel or imageView properties and modify their values directly. The methods of this class also provide a convenient shortcut for configuring the appearance of your string or image. Normally, you configure a button using either a title or an image and size the button accordingly. Buttons can also have a background image, which is positioned behind the content you specify. It’s possible to specify both an image and a title for buttons, which results in the appearance shown in the following image. You can access the current content of a button using the indicated properties. When setting the content of a button, you must specify the title, image, and appearance attributes for each state separately. If you don’t customize the content for a particular state, the button uses the values associated with the Default state and adds any appropriate customizations. For example, in the highlighted state, an image-based button draws a highlight on top of the default image if no custom image is provided. Customize tint color You can specify a custom button tint using the tintColor property. This property sets the color of the button image and text. If you don’t explicitly set a tint color, the button uses its superview’s tint color. Specify edge insets Use insets to add or remove space around the content in your custom or system buttons. You can specify separate insets for your button’s title (titleEdgeInsets), image (imageEdgeInsets), and both the title and image together (contentEdgeInsets). When applied, insets affect the corresponding content rectangle of the button, which the Auto Layout engine uses to determine the button’s position. There should be no reason for you to adjust the edge insets for info, contact, or disclosure buttons. Configure button attributes in Interface Builder The following table lists the core attributes that you configure for buttons in Interface Builder. | | | | | | | The following table lists attributes that affect the button’s appearance. | | | | The following table lists the edge inset attributes for buttons. Use edge inset buttons to alter the rectangle for the button’s content. | | | For information about the button’s inherited Interface Builder attributes, see UIControl and UIView. Support localization To internationalize a button, specify a localized string for the button’s title text. (You may also localize a button’s image as appropriate.) When using storyboards to build your interface, use Xcode’s base internationalization feature to configure the localizations your project supports. When you add a localization, Xcode creates a strings file for that localization. When configuring your interface programmatically, use the system’s built-in support for loading localized strings and resources. For more information about internationalizing your interface, see Internationalization and Localization Guide. Make buttons accessible Buttons are accessible by default. The default accessibility traits for a button are Button and User Interaction Enabled. The accessibility label, traits, and hint are spoken back to the user when VoiceOver is enabled on a device. The button’s title overwrites its accessibility label; even if you set a custom value for the label, VoiceOver speaks the value of the title. VoiceOver speaks this information when a user taps the button once. For example, when a user taps the Options button in Camera, VoiceOver speaks the following: "Options. Button. Shows additional camera options." For more information about making iOS controls accessible, see the accessibility information in UIControl. For general information about making your interface accessible, see Accessibility Programming Guide for iOS. ## Topics ### Creating buttons - [init(frame:)](uikit/uibutton/init(frame:).md) - [init(frame:primaryAction:)](uikit/uibutton/init(frame:primaryaction:).md) - [init(coder:)](uikit/uibutton/init(coder:).md) ### Creating buttons of a specific type - [init(type:)](uikit/uibutton/init(type:).md) - [init(type:primaryAction:)](uikit/uibutton/init(type:primaryaction:).md) - [UIButton.ButtonType](uikit/uibutton/buttontype-swift.enum.md) ### Creating system buttons - [systemButton(with:target:action:)](uikit/uibutton/systembutton(with:target:action:).md) ### Creating buttons from a configuration object - [init(configuration:primaryAction:)](uikit/uibutton/init(configuration:primaryaction:).md) - [UIButton.Configuration](uikit/uibutton/configuration-swift.struct.md) ### Managing the appearance with a configuration object - [configuration](uikit/uibutton/configuration-5rlyb.md) - [automaticallyUpdatesConfiguration](uikit/uibutton/automaticallyupdatesconfiguration.md) - [setNeedsUpdateConfiguration()](uikit/uibutton/setneedsupdateconfiguration().md) - [updateConfiguration()](uikit/uibutton/updateconfiguration().md) - [configurationUpdateHandler](uikit/uibutton/configurationupdatehandler-swift.property.md) - [UIButton.ConfigurationUpdateHandler](uikit/uibutton/configurationupdatehandler-swift.typealias.md) ### Managing the title - [titleLabel](uikit/uibutton/titlelabel.md) - [title(for:)](uikit/uibutton/title(for:).md) - [setTitle(_:for:)](uikit/uibutton/settitle(_:for:).md) - [attributedTitle(for:)](uikit/uibutton/attributedtitle(for:).md) - [setAttributedTitle(_:for:)](uikit/uibutton/setattributedtitle(_:for:).md) - [titleColor(for:)](uikit/uibutton/titlecolor(for:).md) - [setTitleColor(_:for:)](uikit/uibutton/settitlecolor(_:for:).md) - [titleShadowColor(for:)](uikit/uibutton/titleshadowcolor(for:).md) - [setTitleShadowColor(_:for:)](uikit/uibutton/settitleshadowcolor(_:for:).md) ### Managing images and tint color - [backgroundImage(for:)](uikit/uibutton/backgroundimage(for:).md) - [image(for:)](uikit/uibutton/image(for:).md) - [setBackgroundImage(_:for:)](uikit/uibutton/setbackgroundimage(_:for:).md) - [setImage(_:for:)](uikit/uibutton/setimage(_:for:).md) - [preferredSymbolConfigurationForImage(in:)](uikit/uibutton/preferredsymbolconfigurationforimage(in:).md) - [setPreferredSymbolConfiguration(_:forImageIn:)](uikit/uibutton/setpreferredsymbolconfiguration(_:forimagein:).md) - [tintColor](uikit/uibutton/tintcolor.md) ### Specifying the role - [role](uikit/uibutton/role-swift.property.md) - [UIButton.Role](uikit/uibutton/role-swift.enum.md) ### Specifying the behavioral style - [behavioralStyle](uikit/uibutton/behavioralstyle.md) - [preferredBehavioralStyle](uikit/uibutton/preferredbehavioralstyle.md) - [UIBehavioralStyle](uikit/uibehavioralstyle.md) ### Getting the current state - [buttonType](uikit/uibutton/buttontype-swift.property.md) - [currentTitle](uikit/uibutton/currenttitle.md) - [currentAttributedTitle](uikit/uibutton/currentattributedtitle.md) - [currentTitleColor](uikit/uibutton/currenttitlecolor.md) - [currentTitleShadowColor](uikit/uibutton/currenttitleshadowcolor.md) - [currentImage](uikit/uibutton/currentimage.md) - [currentBackgroundImage](uikit/uibutton/currentbackgroundimage.md) - [currentPreferredSymbolConfiguration](uikit/uibutton/currentpreferredsymbolconfiguration.md) - [imageView](uikit/uibutton/imageview.md) - [subtitleLabel](uikit/uibutton/subtitlelabel.md) ### Supporting pointer interactions - [isPointerInteractionEnabled](uikit/uibutton/ispointerinteractionenabled.md) - [isHovered](uikit/uibutton/ishovered.md) - [pointerStyleProvider](uikit/uibutton/pointerstyleprovider-y4eb.md) - [UIButton.PointerStyleProvider](uikit/uibutton/pointerstyleprovider-swift.typealias.md) - [UIButtonPointerStyleProvider](uikit/uibuttonpointerstyleprovider.md) ### Supporting menu and toggle buttons - [menu](uikit/uibutton/menu.md) - [isHeld](uikit/uibutton/isheld.md) - [changesSelectionAsPrimaryAction](uikit/uibutton/changesselectionasprimaryaction.md) - [preferredMenuElementOrder](uikit/uibutton/preferredmenuelementorder.md) ### Deprecated - [Deprecated symbols](uikit/uibutton-deprecated-symbols.md) ## Relationships ### Inherits From - [UIControl](uikit/uicontrol.md) ### Conforms To - [CALayerDelegate](quartzcore/calayerdelegate.md) - [CLBodyIdentifiable](corelocation/clbodyidentifiable.md) - [CMBodyIdentifiable](coremotion/cmbodyidentifiable.md) - [CVarArg](swift/cvararg.md) - [Copyable](swift/copyable.md) - [CustomDebugStringConvertible](swift/customdebugstringconvertible.md) - [CustomStringConvertible](swift/customstringconvertible.md) - [Equatable](swift/equatable.md) - [Escapable](swift/escapable.md) - [Hashable](swift/hashable.md) - [NSCoding](foundation/nscoding.md) - [NSObjectProtocol](objectivec/nsobjectprotocol.md) - [NSTouchBarProvider](appkit/nstouchbarprovider.md) - [Sendable](swift/sendable.md) - [SendableMetatype](swift/sendablemetatype.md) - [UIAccessibilityContentSizeCategoryImageAdjusting](uikit/uiaccessibilitycontentsizecategoryimageadjusting.md) - [UIAccessibilityIdentification](uikit/uiaccessibilityidentification.md) - [UIActivityItemsConfigurationProviding](uikit/uiactivityitemsconfigurationproviding.md) - [UIAppearance](uikit/uiappearance.md) - [UIAppearanceContainer](uikit/uiappearancecontainer.md) - [UIContextMenuInteractionDelegate](uikit/uicontextmenuinteractiondelegate.md) - [UICoordinateSpace](uikit/uicoordinatespace.md) - [UIDynamicItem](uikit/uidynamicitem.md) - [UIFocusEnvironment](uikit/uifocusenvironment.md) - [UIFocusItem](uikit/uifocusitem.md) - [UIFocusItemContainer](uikit/uifocusitemcontainer.md) - [UILargeContentViewerItem](uikit/uilargecontentvieweritem.md) - [UIPasteConfigurationSupporting](uikit/uipasteconfigurationsupporting.md) - [UIPopoverPresentationControllerSourceItem](uikit/uipopoverpresentationcontrollersourceitem.md) - [UIResponderStandardEditActions](uikit/uiresponderstandardeditactions.md) - [UISpringLoadedInteractionSupporting](uikit/uispringloadedinteractionsupporting.md) - [UITraitChangeObservable](uikit/uitraitchangeobservable-67e94.md) - [UITraitEnvironment](uikit/uitraitenvironment.md) - [UIUserActivityRestoring](uikit/uiuseractivityrestoring.md) ## See Also ### Controls - [Responding to control-based events using target-action](uikit/responding-to-control-based-events-using-target-action.md) - [UIControl](uikit/uicontrol.md) - [UIColorWell](uikit/uicolorwell.md) - [UIDatePicker](uikit/uidatepicker.md) - [UIPageControl](uikit/uipagecontrol.md) - [UISegmentedControl](uikit/uisegmentedcontrol.md) - [UISlider](uikit/uislider.md) - [UIStepper](uikit/uistepper.md) - [UISwitch](uikit/uiswitch.md)