Skip to content

UIButton ​

UIButton represents a button: a tappable area on screen that displays a title, an image, or both. When the user taps the button, it fires the click event.

A button's title, title color, image, and background image are set per state, and the button displays the set for its current state.

A button is a control: enabling, state, and events come from UIControl. A control is in turn a view: position, size, background color, and corner radius come from UIView.

Inheritance: EventTarget → NSObject → UIResponder → UIView → UIControl → UIButton

For how to build a working button, see the guide Building a button.

Constructor ​

UIButton()

Creates a button of type custom. The system gives it no default appearance.

Static methods ​

UIButton.buttonWithType()

Creates a button of the given type. For an ordinary text button, use 'system'.

Instance properties ​

Also inherits properties from UIControl and UIView. Inherited properties commonly used with buttons are isEnabled, isSelected, backgroundColor, and layer.

PropertyDescription
buttonType read-onlyThe button's type, fixed at creation
roleThe button's purpose. The system adjusts the appearance based on it
currentTitle read-onlyThe title the button is displaying right now
currentTitleColor read-onlyThe button's title color right now
currentImage read-onlyThe image the button is displaying right now
currentBackgroundImage read-onlyThe background image the button is displaying right now
currentAttributedTitle read-onlyThe styled title the button is displaying right now
titleLabel read-onlyThe UILabel that displays the title. Use it to set the font and number of lines
imageView read-onlyThe UIImageView that displays the image

Instance methods ​

Also inherits methods from UIControl and UIView.

The setter methods all take { forState } and set a value for one or more states:

MethodDescription
setTitle()Sets the title
setTitleColor()Sets the title color
setImage()Sets the image, shown to the left of the title
setBackgroundImage()Sets the background image, which fills the whole button
setAttributedTitle()Sets a styled title

The getter methods each read one state:

MethodDescription
titleForState()The title for a state
titleColorForState()The title color for a state
imageForState()The image for a state
backgroundImageForState()The background image for a state
attributedTitleForState()The styled title for a state

Events ​

A button's events are all inherited from UIControl; listen with addEventListener(). These are the ones buttons commonly use:

EventWhen it fires
clickThe user completed a tap. Use this to respond to taps
touchdownA finger just touched down
touchupinsideThe finger lifted inside the button
touchupoutsideThe finger touched down, slid outside the button, and lifted
touchcancelThe system interrupted the touch, for example an incoming call

For all 16 events, what the event object carries, and when callbacks run, see UIControl.

States ​

At any moment a button is in one or more states. The methods that set titles, colors, and images use forState to specify which states to set.

StateWhen the button is in itWho switches it
normalWhen none of the others apply—
highlightedA finger is pressing the buttonThe system
disabledisEnabled is falseThe app's code
selectedisSelected is trueThe app's code
focusedThe button has received focus. When it receives focus is not verified in the simulatorThe system
  • States that haven't been set separately use the normal set. So most buttons only set normal.
  • Several states can hold at once, for example selected and disabled. For a value used only in that combination, write forState as ['selected', 'disabled'].
  • Read the current state from the inherited state property, which returns an array of state names.

Examples ​

A button in the center of the screen ​

Starting from a blank app, place a button in the center of the screen that prints a line to the console when tapped.

js
application.addEventListener('sceneconnect', (e) => {
  const win = new UIWindow(e.scene);
  const page = new UIViewController();
  page.view.backgroundColor = 'systemBackground';
  win.rootViewController = page;
  win.makeKeyAndVisible();

  const button = UIButton.buttonWithType('system');
  button.setTitle('Tap me', { forState: ['normal'] });
  button.addEventListener('click', () => {
    console.log('Button tapped');
  });

  button.translatesAutoresizingMaskIntoConstraints = false;
  page.view.addSubview(button);
  NSLayoutConstraint.activateConstraints([
    button.centerXAnchor.constraintEqualToAnchor(page.view.centerXAnchor),
    button.centerYAnchor.constraintEqualToAnchor(page.view.centerYAnchor),
  ]);
});

Effect

  • A blue "Tap me" appears in the center of the screen, with no border or background.
  • While a finger presses it, the title fades; it returns on release.
  • Tap it once and the console prints Button tapped.

This code has not been run as a whole in the simulator. Each API it uses has been run in the acceptance tests.

Different titles per state ​

js
const follow = UIButton.buttonWithType('system');
follow.setTitle('Follow', { forState: ['normal'] });
follow.setTitle('Following', { forState: ['selected'] });

follow.addEventListener('click', () => {
  follow.isSelected = !follow.isSelected;
});

Effect: It initially shows "Follow"; tap once and it becomes "Following"; tap again and it changes back. Not verified in the simulator.

For more patterns, see the guide Building a button.

Corresponding iOS API ​

ObjCJS
[UIButton buttonWithType:UIButtonTypeSystem]UIButton.buttonWithType('system')
[btn setTitle:@"Tap me" forState:UIControlStateNormal]btn.setTitle('Tap me', { forState: ['normal'] })
[btn setTitle:@"x" forState:UIControlStateSelected | UIControlStateDisabled]btn.setTitle('x', { forState: ['selected', 'disabled'] })
[btn titleForState:UIControlStateHighlighted]btn.titleForState('highlighted')
[btn addTarget:self action:@selector(tap) forControlEvents:UIControlEventPrimaryActionTriggered]btn.addEventListener('click', tap)
btn.role = UIButtonRoleDestructivebtn.role = 'destructive'
btn.enabled = NObtn.isEnabled = false

See also ​