Introduction

Setting UIButton title text color in iOS seems simple, but results can differ by control state, configuration API, and tint behavior. Developers often set one color and then wonder why highlighted or disabled states look wrong. A robust solution defines title colors per state and keeps styling consistent with modern button configuration APIs.

Basic Title Color With Classic API

The classic method is setTitleColor.

let button = UIButton(type: .system)
button.setTitle("Save", for: .normal)
button.setTitleColor(.systemBlue, for: .normal)

You should usually set colors for additional states.

button.setTitleColor(.white, for: .highlighted)
button.setTitleColor(.lightGray, for: .disabled)

Without this, iOS may apply automatic dimming that does not match design.

UIButton State-Specific Styling

Common states to style:

• normal
• highlighted
• disabled
• selected

button.setTitleColor(.systemBlue, for: .normal)
button.setTitleColor(.systemIndigo, for: .selected)
button.setTitleColor(.systemGray, for: .disabled)

Keep state semantics clear, especially if selected state means toggled mode.

Working With UIButton.Configuration

On iOS fifteen and later, UIButton.Configuration is often preferred.

1var config = UIButton.Configuration.filled()
2config.title = "Continue"
3config.baseForegroundColor = .white
4config.baseBackgroundColor = .systemBlue
5
6let button = UIButton(configuration: config, primaryAction: nil)

When using configuration, old APIs may be overridden by configuration updates, so keep styling model consistent.

Attributed Title Colors

If title uses attributed strings, text color can come from attributes instead of setTitleColor.

1let attrs: [NSAttributedString.Key: Any] = [
2    .foregroundColor: UIColor.systemRed,
3    .font: UIFont.boldSystemFont(ofSize: 16)
4]
5button.setAttributedTitle(NSAttributedString(string: "Delete", attributes: attrs), for: .normal)

Do not mix many independent color sources unless necessary.

Dynamic Color and Dark Mode

Prefer semantic colors for dark mode compatibility.

button.setTitleColor(.label, for: .normal)
button.setTitleColor(.secondaryLabel, for: .disabled)

Hardcoded colors may fail contrast in dark appearance.

Debugging Unexpected Title Color

If color appears wrong, inspect:

• current button state
• attributed title presence
• configuration update handlers
• inherited tint color and appearance proxies

State transitions during touch events can make it seem like color assignment is ignored when the button is actually in highlighted state.

Updating Colors During State Changes

When state changes programmatically, update button appearance in one method to avoid drift.

1func applyButtonState(_ button: UIButton, enabled: Bool) {
2    button.isEnabled = enabled
3    button.setTitleColor(enabled ? .white : .secondaryLabel, for: .normal)
4    button.backgroundColor = enabled ? .systemBlue : .systemGray5
5}

Centralized state styling prevents conflicting updates from scattered view controllers.

Legacy and Modern API Interoperability

If you use UIButton.Configuration and also call setTitleColor, final result depends on configuration update cycle. Prefer one style strategy per button class.

For teams supporting older iOS and newer iOS simultaneously, create wrapper helpers that branch by availability and keep color intent consistent across both implementations.

Accessibility Validation

Always verify text contrast in enabled, disabled, and highlighted states with accessibility inspector. A title color that looks fine in normal state can fail readability during touch highlight transitions.

This validation should be part of UI review checklist.

Keep style tokens centralized.

Common Pitfalls

• Setting color for normal state only and ignoring others.
• Mixing configuration API with legacy setters inconsistently.
• Overriding title color unintentionally with attributed titles.
• Using hardcoded colors that fail dark mode contrast.
• Styling based on assumed state rather than current control state.

Summary

• Use setTitleColor per state for predictable button title styling.
• Prefer semantic colors for appearance compatibility.
• With modern configuration API, keep one styling approach consistent.
• Check attributed title and state transitions when debugging color issues.
• Define explicit disabled and highlighted colors for polished UX.