Introduction

Circular images are common in iOS UIs for avatars, contacts, and profile cards. The effect is visually simple, but it only works correctly if the image view is square and the clipping is applied after layout. The exact implementation differs between UIKit and SwiftUI, but the geometry rule is the same in both.

UIKit: Use Corner Radius and Clipping

In UIKit, the standard pattern is:

• use a square UIImageView
• set contentMode to .scaleAspectFill
• enable clipping
• set the corner radius to half the width

1import UIKit
2
3final class ProfileViewController: UIViewController {
4    @IBOutlet private weak var avatarImageView: UIImageView!
5
6    override func viewDidLoad() {
7        super.viewDidLoad()
8        avatarImageView.image = UIImage(named: "avatar")
9        avatarImageView.contentMode = .scaleAspectFill
10        avatarImageView.clipsToBounds = true
11    }
12
13    override func viewDidLayoutSubviews() {
14        super.viewDidLayoutSubviews()
15        avatarImageView.layer.cornerRadius = avatarImageView.bounds.width / 2
16    }
17}

The radius is set in viewDidLayoutSubviews because Auto Layout may not have produced the final size during viewDidLoad.

A Circle Requires a Square Frame

If the view is wider than it is tall, the result is an oval, not a circle. That is why the width-equals-height rule matters more than the rounding code itself.

1func constrainSquare(_ imageView: UIImageView, diameter: CGFloat) {
2    imageView.translatesAutoresizingMaskIntoConstraints = false
3    NSLayoutConstraint.activate([
4        imageView.widthAnchor.constraint(equalToConstant: diameter),
5        imageView.heightAnchor.constraint(equalTo: imageView.widthAnchor)
6    ])
7}

Without a square frame, the layer math is correct but the output shape is still wrong.

SwiftUI: clipShape(Circle())

SwiftUI expresses the same effect more directly.

1import SwiftUI
2
3struct AvatarView: View {
4    let image: Image
5
6    var body: some View {
7        image
8            .resizable()
9            .scaledToFill()
10            .frame(width: 88, height: 88)
11            .clipShape(Circle())
12            .overlay(Circle().stroke(Color.white, lineWidth: 2))
13    }
14}

This is the declarative equivalent of a circular mask plus optional border.

Remote Images Need Consistent Sizing

If the image comes from the network, keep the placeholder and final image frame identical so the layout does not jump.

1import SwiftUI
2
3struct RemoteAvatarView: View {
4    let url: URL
5
6    var body: some View {
7        AsyncImage(url: url) { phase in
8            switch phase {
9            case .success(let image):
10                image.resizable().scaledToFill()
11            case .empty:
12                Color.gray.opacity(0.3)
13            case .failure(_):
14                Color.gray
15            @unknown default:
16                Color.gray
17            }
18        }
19        .frame(width: 72, height: 72)
20        .clipShape(Circle())
21    }
22}

That keeps list cells stable while images load.

Reuse the Style Instead of Duplicating It

If circular images appear across many screens, wrap the styling in a reusable helper or view. That keeps borders, shadows, and sizing consistent and avoids repeating fragile UI code in every controller.

In scrolling lists, also downsample large images and use an image-loading library when appropriate so circular masking does not become an excuse for poor scrolling performance.

If you add borders or shadows, keep them part of the reusable component too. Otherwise different screens quickly drift into slightly different avatar styles that are harder to keep consistent.

That kind of visual drift is small at first, but it becomes noticeable quickly in apps with many profile or contact surfaces. Consistency matters.

Common Pitfalls

• Setting the corner radius before Auto Layout has finalized the frame.
• Using a non-square image view and expecting a perfect circle.
• Forgetting to clip the image so the corners remain visible.
• Letting placeholders and loaded images use different sizes.

Summary

• A circular image requires both a square frame and clipping.
• In UIKit, set the corner radius to half the width after layout.
• In SwiftUI, use clipShape(Circle()).
• Keep remote-image placeholders the same size as the final image.
• Centralize avatar styling instead of duplicating it across screens.