Introduction

Getting a UIButton title to display on two lines is more than setting numberOfLines = 2. The button also needs enough width, alignment, and layout constraints so the label can actually wrap. Most failures come from Auto Layout or title-edge assumptions rather than from the UIButton API itself.

What Actually Controls Multi-Line Button Titles

The visible text inside a button is rendered by titleLabel, which is a UILabel. That means multi-line behavior depends on normal label rules:

• 'numberOfLines must allow more than one line.'
• 'lineBreakMode must allow wrapping.'
• The label must have a constrained width.
• The button must have enough height.

If any one of those conditions is missing, the title stays on one line or gets truncated.

Basic Programmatic Setup

This is a minimal working example in UIKit:

1import UIKit
2
3final class ViewController: UIViewController {
4    override func viewDidLoad() {
5        super.viewDidLoad()
6        view.backgroundColor = .systemBackground
7
8        let button = UIButton(type: .system)
9        button.translatesAutoresizingMaskIntoConstraints = false
10        button.setTitle("Search Products\nNear You", for: .normal)
11        button.titleLabel?.numberOfLines = 2
12        button.titleLabel?.lineBreakMode = .byWordWrapping
13        button.titleLabel?.textAlignment = .center
14
15        view.addSubview(button)
16
17        NSLayoutConstraint.activate([
18            button.centerXAnchor.constraint(equalTo: view.centerXAnchor),
19            button.centerYAnchor.constraint(equalTo: view.centerYAnchor),
20            button.widthAnchor.constraint(equalToConstant: 160),
21            button.heightAnchor.constraint(greaterThanOrEqualToConstant: 60)
22        ])
23    }
24}

The fixed width is important. Without it, Auto Layout may let the button expand horizontally instead of wrapping.

Why numberOfLines = 2 Often Appears Not to Work

A common mistake is setting titleLabel?.numberOfLines = 2 but leaving the button with no width constraint. In that case, the title has no reason to wrap.

Another common issue is using a short title and expecting two lines automatically. Wrapping happens only when line width forces it or when you include an explicit line break.

If you want exactly two lines regardless of width, include a newline in the title string:

button.setTitle("Primary Line\nSecondary Line", for: .normal)

If you want natural wrapping, rely on width and word wrapping instead of embedded newline characters.

Interface Builder Setup

If you configure the button in Storyboard or XIB:

• Set the title normally.
• Add width or leading/trailing constraints that limit label width.
• In code, set numberOfLines and lineBreakMode.

Example outlet configuration:

1@IBOutlet weak var actionButton: UIButton!
2
3override func viewDidLoad() {
4    super.viewDidLoad()
5    actionButton.titleLabel?.numberOfLines = 2
6    actionButton.titleLabel?.lineBreakMode = .byWordWrapping
7    actionButton.titleLabel?.textAlignment = .center
8}

It is usually safer to configure these properties in code, because Interface Builder support for title label behavior is limited.

Improve Layout With Insets and Configuration API

If text feels cramped, add content insets. On modern iOS, UIButton.Configuration is also useful for layout clarity.

1import UIKit
2
3var config = UIButton.Configuration.filled()
4config.title = "Create Account\nStart Free Trial"
5config.titleAlignment = .center
6config.contentInsets = NSDirectionalEdgeInsets(top: 10, leading: 16, bottom: 10, trailing: 16)
7
8let button = UIButton(configuration: config)
9button.titleLabel?.numberOfLines = 2
10button.titleLabel?.lineBreakMode = .byWordWrapping

Insets help maintain readable spacing without manually adjusting label frames.

Dynamic Type and Localization

Two-line titles become more fragile when font size increases or localized text becomes longer. Test with:

• Larger accessibility text sizes.
• Longer translated strings.
• Narrow device widths.

In some languages, a label that fits in two lines in English may need three lines. If exactly two lines is a strict design rule, product copy and localization teams need to know that constraint.

Debugging Checklist

If wrapping still fails, verify:

• 'titleLabel?.numberOfLines is set after button creation.'
• Button width is constrained.
• 'lineBreakMode is .byWordWrapping.'
• No configuration or style code later overwrites label settings.
• Button has enough vertical space.

Inspect in Xcode view debugger if needed. It quickly reveals whether the label frame is too wide or too short.

Common Pitfalls

• Setting numberOfLines without constraining button width.
• Expecting two lines automatically when the title still fits on one line.
• Forgetting to center-align text, making wrapped titles look visually wrong.
• Ignoring Dynamic Type and localization, which can break carefully tuned layouts.
• Debugging the label while another configuration object silently resets button properties.

Summary

• A two-line UIButton title needs both label configuration and correct layout constraints.
• 'numberOfLines = 2 alone is not enough if the button is unconstrained in width.'
• Use word wrapping for natural breaks and newline characters for explicit breaks.
• Test with Dynamic Type and localized text before treating the layout as finished.
• When debugging, check width, line-break mode, and later configuration overrides first.