Fix: UIButton multiline text not wrapping in Swift

Fix: UIButton multiline text not wrapping in Swift

Written by

in

Quick answer: Use UIButton’s built-in titleLabel instead of adding a separate UILabel. Set its numberOfLines to 0, lineBreakMode to .byWordWrapping, and textAlignment to .center, then assign the text with setTitle(_:for:). Give the button enough width and height to display the wrapped title.

Why this happens

A UIButton already manages a label for its title. Adding another UILabel as a subview creates a separate piece of content that does not participate in the button’s normal title layout or state handling. Trying to fix its visibility with bringSubviewToFront(_:) does not address that underlying mismatch.

Multiline titles also need two things: a wrapping policy and enough space. A title can support word wrapping but still look like a single line if the button is too wide, or appear clipped if its height only accommodates one line.

The direct fix is to configure the existing titleLabel and set the title through the button’s API. For buttons using UIButton.Configuration, configure the title through that configuration instead.

How to fix it

1. Configure the button’s existing title label

Remove the extra UILabel and use the label that belongs to the button:

import UIKit

func configureMultilineTitle(for button: UIButton) {
    button.titleLabel?.numberOfLines = 0
    button.titleLabel?.lineBreakMode = .byWordWrapping
    button.titleLabel?.textAlignment = .center

    button.setTitle("First line\nSecond line", for: .normal)
}

Each setting has a different purpose:

  • numberOfLines = 0 allows as many lines as the layout can display.
  • .byWordWrapping wraps text at word boundaries when the available width is insufficient.
  • .center centers the text within the title label.
  • \n requests an explicit line break.

You do not need a newline for automatic wrapping. For example:

button.setTitle(
    "Continue with the selected delivery address",
    for: .normal
)

This title wraps only when its available width requires it. Use explicit newlines for deliberately separated phrases, not as a workaround for every screen width.

The accepted solution uses the same underlying approach: configure the built-in label’s word wrapping and alignment, then set a title containing a newline. Explicitly setting numberOfLines makes the intended line limit clear as well.

For an Objective-C project, the equivalent is:

#import <UIKit/UIKit.h>

button.titleLabel.numberOfLines = 0;
button.titleLabel.lineBreakMode = NSLineBreakByWordWrapping;
button.titleLabel.textAlignment = NSTextAlignmentCenter;
[button setTitle:@"First line\nSecond line"
        forState:UIControlStateNormal];

Use the current enum names shown here rather than the older UILineBreakModeWordWrap and UITextAlignmentCenter names found in historical examples.

2. Give the wrapped title enough layout space

If the title still appears cut off, inspect the button’s constraints before changing its subview order.

A fixed height designed for a single line can clip a two-line title. Similarly, a button that stretches across a very wide container may never need to wrap.

This example creates an intentionally bounded area for a short, two-line title:

import UIKit

final class MultilineButtonViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        let button = UIButton(type: .system)
        button.translatesAutoresizingMaskIntoConstraints = false
        button.titleLabel?.numberOfLines = 0
        button.titleLabel?.lineBreakMode = .byWordWrapping
        button.titleLabel?.textAlignment = .center
        button.setTitle(
            "Review details\nand continue",
            for: .normal
        )

        view.addSubview(button)

        NSLayoutConstraint.activate([
            button.centerXAnchor.constraint(
                equalTo: view.safeAreaLayoutGuide.centerXAnchor
            ),
            button.centerYAnchor.constraint(
                equalTo: view.safeAreaLayoutGuide.centerYAnchor
            ),
            button.widthAnchor.constraint(equalToConstant: 260),
            button.heightAnchor.constraint(equalToConstant: 100)
        ])
    }
}

The dimensions make this a focused demonstration, not a universal production size. Longer translations and larger accessibility text sizes may need more height.

When debugging your own layout:

  1. Confirm that the button has a known available width.
  2. Temporarily increase its height to distinguish clipping from a wrapping problem.
  3. Check for conflicting width or height constraints.
  4. Check whether the button sits inside another view that clips its contents.
  5. Replace temporary dimensions with sizing appropriate to your actual content.

Do not assume that allowing unlimited lines automatically makes every existing button layout grow vertically. Text configuration and layout constraints must agree.

3. Use UIButton.Configuration for configured buttons

On iOS 15 and later, UIButton.Configuration provides a separate, modern way to describe a button’s content and appearance. If your button already uses a configuration, keep its title settings there:

import UIKit

@available(iOS 15.0, *)
func makeConfiguredButton() -> UIButton {
    var configuration = UIButton.Configuration.filled()
    configuration.title = "Review details\nand continue"
    configuration.titleAlignment = .center
    configuration.titleLineBreakMode = .byWordWrapping
    configuration.contentInsets = NSDirectionalEdgeInsets(
        top: 12,
        leading: 16,
        bottom: 12,
        trailing: 16
    )

    return UIButton(configuration: configuration)
}

The explicit newline requests two lines, while titleLineBreakMode defines the wrapping behavior. The directional insets leave space around the title.

The returned button still needs a frame or Auto Layout constraints. A configuration does not remove the need to check available space.

For an existing configured button, copy its configuration, update it, and assign it back:

if var configuration = button.configuration {
    configuration.title = "Review details\nand continue"
    configuration.titleAlignment = .center
    configuration.titleLineBreakMode = .byWordWrapping
    button.configuration = configuration
}

Avoid scattering title updates across setTitle, direct label changes, and configuration updates. If a configuration update handler changes the title, make the multiline settings part of that configuration logic too.

4. Check storyboard settings and state-specific titles

For a storyboard-based button, select it and inspect its title and line-break settings in the Attributes inspector. Choose Word Wrap for the line-break behavior where that control is available. Inspector options differ between traditional buttons and configuration-based button styles.

You do not need attributed text merely to enable multiple lines. A plain title supports both explicit newlines and wrapping. Use an attributed title when you actually need character-level styling.

Also inspect any titles assigned for other control states. A highlighted, selected, or disabled title may differ from the normal title. If wrapping changes only after interaction, check those values and any code that updates the button’s configuration.

How to prevent it

  • Use the button’s title APIs instead of overlaying a separate label for ordinary text titles.
  • Keep configuration-based title changes in one place.
  • Test long localized titles and larger accessibility text sizes.
  • Avoid assuming that a one-line height will accommodate wrapped content.
  • Use explicit newlines only when the line break is part of the intended wording.
  • Check normal, highlighted, selected, and disabled appearances when they have custom titles.

FAQ

Why does my UIButton title still show only one line?

Check both the line limit and the available width. Set titleLabel?.numberOfLines to 0 for a traditional button, enable word wrapping, and verify that no later code replaces those settings. A short title in a wide button will naturally remain on one line.

Do I need to add a UILabel to make a multiline button?

No. UIButton already has a title label, and adding another label introduces unnecessary layout and state-management work. Use a separate custom content arrangement only when your design genuinely requires more than the standard title and image layout.

Why is the title centered but still clipped?

Text alignment changes where text sits within the label; it does not increase the button’s height. Check the button’s height constraints, surrounding layout, and content insets, then verify the result with the longest title and largest supported text sizes.

Sources & credits

Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.