Introduction

Changing the text on a UIButton in Swift is straightforward, but the correct API is easy to miss if you are editing older Xcode 6 era code. The important detail is that a button can have different titles for different control states, so you normally set the title with setTitle rather than editing the label directly.

If you only assign button.titleLabel?.text, the visible title may not update the way you expect. UIButton manages its displayed title through state-aware methods.

Use setTitle for the Correct Control State

In Xcode 6 era Swift, the common form looked like this:

1import UIKit
2
3class ViewController: UIViewController {
4    @IBOutlet weak var actionButton: UIButton!
5
6    override func viewDidLoad() {
7        super.viewDidLoad()
8        actionButton.setTitle("Start", forState: UIControlState.Normal)
9    }
10}

That sets the title shown for the normal state of the button. In newer Swift syntax the same call is written with for: .normal, but the idea is unchanged.

Update the Title in Response to User Actions

Most real apps change button text after a tap, after loading data, or after a form becomes valid. The pattern is the same: keep a reference to the button, then call setTitle when state changes.

1import UIKit
2
3class ViewController: UIViewController {
4    @IBOutlet weak var saveButton: UIButton!
5
6    @IBAction func saveTapped(sender: UIButton) {
7        saveButton.setTitle("Saved", forState: UIControlState.Normal)
8    }
9}

This is preferable to editing subviews inside the button because it keeps the title consistent with the button’s state management.

Set Titles for Multiple States

A button can show different text while highlighted, selected, or disabled. That is useful when the app wants the UI to communicate status without swapping controls.

1import UIKit
2
3class ViewController: UIViewController {
4    @IBOutlet weak var submitButton: UIButton!
5
6    override func viewDidLoad() {
7        super.viewDidLoad()
8        submitButton.setTitle("Submit", forState: UIControlState.Normal)
9        submitButton.setTitle("Submitting...", forState: UIControlState.Disabled)
10        submitButton.enabled = false
11    }
12}

If you only change the normal-state title but the button is currently disabled or selected, you may think the code failed when the visible state is actually using a different title.

Interface Builder and Outlet Checks

If the title does not change, verify the outlet first. In older storyboard-based projects it is common to have the outlet disconnected after a rename or layout edit. If the outlet is nil, your code will not update the button you think it is updating.

You should also confirm that no storyboard configuration is immediately replacing your programmatic change. For example, if another action method or setup block runs later and calls setTitle again, the earlier change will appear to “not work” even though it did run.

Another practical check is to put the title change in viewDidLoad or in the exact action method that owns the state transition. If the change is spread across several callbacks, the last one wins, and debugging becomes harder than the problem really is.

Common Pitfalls

• Using titleLabel?.text instead of setTitle.
• Updating the title for .Normal while the button is currently disabled or selected.
• Calling the code before the outlet is connected.
• Forgetting to connect the UIButton outlet after editing the storyboard.
• Mixing older Xcode 6 syntax with newer Swift syntax without checking the project’s compiler version.

Summary

• Use setTitle to change a button’s text in Swift.
• In Xcode 6 era Swift, the common form is setTitle("Text", forState: UIControlState.Normal).
• Buttons can have different titles for different states, so update the correct one.
• Do not rely on titleLabel?.text for normal button-title changes.
• If the title does not update, check outlet wiring and when the code runs.