Introduction

A common iOS UI frustration is setting a button image to aspect fit and seeing no visible change. Developers often set button.imageView?.contentMode = .scaleAspectFit and expect the icon to resize correctly, but the image still appears stretched, clipped, or centered with incorrect padding. This happens because UIButton layout is influenced by several layers: the button frame, edge insets, image view frame, Auto Layout constraints, and on modern iOS, UIButton.Configuration behavior.

In other words, contentMode alone is rarely enough. You need to control the image container size and the button’s layout model together. Once those constraints are explicit, aspect fit works consistently across device sizes and Dynamic Type changes.

Core Sections

1. Use the correct API for your button style

For iOS 15+, prefer UIButton.Configuration; for older code paths, configure the embedded image view directly.

1let button = UIButton(type: .system)
2button.setImage(UIImage(named: "profile"), for: .normal)
3button.imageView?.contentMode = .scaleAspectFit
4button.contentHorizontalAlignment = .fill
5button.contentVerticalAlignment = .fill
6button.imageEdgeInsets = UIEdgeInsets(top: 8, left: 8, bottom: 8, right: 8)

With configuration-based buttons:

1var config = UIButton.Configuration.plain()
2config.image = UIImage(systemName: "person.circle")
3config.imagePlacement = .leading
4config.imagePadding = 8
5config.contentInsets = NSDirectionalEdgeInsets(top: 8, leading: 12, bottom: 8, trailing: 12)
6
7let button = UIButton(configuration: config)

Do not mix old inset APIs and configuration APIs blindly; configuration may override legacy properties.

2. Constrain button dimensions to a realistic image box

Aspect fit preserves proportions inside available bounds. If the image view gets a tiny or ambiguous frame, the result looks wrong even with correct mode.

1button.translatesAutoresizingMaskIntoConstraints = false
2NSLayoutConstraint.activate([
3    button.widthAnchor.constraint(equalToConstant: 120),
4    button.heightAnchor.constraint(equalToConstant: 44)
5])

If the icon should dominate the button, allocate more vertical space and reduce title impact or remove the title.

button.setTitle(nil, for: .normal)
button.imageView?.clipsToBounds = true

In stack views, low hugging/compression priorities can collapse button height unexpectedly, which makes the image appear cropped.

3. Debug layout with runtime inspection

Inspect actual frames after layout:

1override func viewDidLayoutSubviews() {
2    super.viewDidLayoutSubviews()
3    print("button frame:", button.frame)
4    print("image frame:", button.imageView?.frame ?? .zero)
5}

If imageView frame is not what you expect, check conflicting constraints or state-specific configuration updates. It is common to set the image for .normal only and forget .highlighted or .selected, then think aspect fit is inconsistent.

4. Handle SF Symbols and bitmap assets differently

SF Symbols scale with point size and weight. Bitmap assets depend on pixel dimensions and rendering mode. For symbols, control symbol configuration:

1let symbol = UIImage(systemName: "bell.fill")?.applyingSymbolConfiguration(
2    .init(pointSize: 18, weight: .medium)
3)
4button.setImage(symbol, for: .normal)

For bitmap assets, provide correctly sized @2x/@3x resources. Aspect fit cannot fix low-resolution images that are too small for the target frame.

Common Pitfalls

• Setting imageView.contentMode without giving the button a stable frame through constraints.
• Mixing UIButton.Configuration and legacy insets/properties, causing hidden overrides.
• Forgetting state-specific images, so pressed or selected states use different sizing behavior.
• Expecting aspect fit to repair poor source assets instead of supplying proper image dimensions.
• Embedding the button in stack views where compression priorities shrink it below usable icon size.

Summary

When a UIButton refuses to behave like aspect fit, the issue is usually layout ownership, not the aspect mode itself. Define button size explicitly, use a single configuration model, and verify the actual imageView frame at runtime. Separate handling for SF Symbols versus bitmap assets, and ensure all control states are configured consistently. With those constraints in place, .scaleAspectFit works predictably across iPhone sizes and avoids the stretched-or-clipped icon issues that make UI polish difficult.

A practical way to keep this issue from returning is to turn the fix into a lightweight runbook. Capture the exact environment assumptions (tool versions, runtime flags, cluster or platform settings, and required dependencies), then store a short verification command sequence that any teammate can run from a clean setup. This makes troubleshooting deterministic instead of person-dependent and reduces rework during on-call incidents.

It also helps to add one automated guardrail in CI or pre-deploy checks that validates the critical assumption described above. That guardrail might be a linter rule, a smoke test, a schema check, a policy validation step, or a minimal integration test. When the same class of failure is caught before release, teams spend less time on emergency debugging and more time on controlled improvements.