Introduction

If you want a small icon inline with label text on iOS, the usual solution is an attributed string with an NSTextAttachment. That gives you much better control than trying to fake the effect with separate image and label views, especially when the icon must sit naturally inside the text flow.

Basic Inline Icon with NSTextAttachment

Create an attachment, give it an image, and insert it into a mutable attributed string before or after the text.

1import UIKit
2
3let label = UILabel()
4label.font = .systemFont(ofSize: 16)
5
6let attachment = NSTextAttachment()
7attachment.image = UIImage(systemName: "star.fill")
8attachment.bounds = CGRect(x: 0, y: -2, width: 14, height: 14)
9
10let iconString = NSAttributedString(attachment: attachment)
11let textString = NSAttributedString(string: " Featured item")
12
13let combined = NSMutableAttributedString()
14combined.append(iconString)
15combined.append(textString)
16
17label.attributedText = combined

The bounds adjustment is important because an attachment often sits a little too low relative to the text baseline unless you nudge it.

Sizing the Icon to Match the Font

Hard-coding the icon size is fine for small cases, but you often get a better result by deriving the image size from the label font:

1import UIKit
2
3func attributedLabelText(text: String, symbolName: String, font: UIFont) -> NSAttributedString {
4    let attachment = NSTextAttachment()
5    attachment.image = UIImage(systemName: symbolName)
6
7    let iconSize = font.capHeight
8    attachment.bounds = CGRect(x: 0, y: (font.descender / 2), width: iconSize, height: iconSize)
9
10    let result = NSMutableAttributedString(attachment: attachment)
11    result.append(NSAttributedString(string: " " + text, attributes: [
12        .font: font
13    ]))
14    return result
15}
16
17let label = UILabel()
18label.font = .systemFont(ofSize: 17)
19label.attributedText = attributedLabelText(
20    text: "Synced",
21    symbolName: "checkmark.circle.fill",
22    font: label.font
23)

Using the font metrics keeps the icon visually aligned when the text size changes.

Tinting the Embedded Icon

If you use SF Symbols or template images, tint the attachment image before assigning it:

1let baseImage = UIImage(systemName: "bolt.fill")
2let tinted = baseImage?.withTintColor(.systemYellow, renderingMode: .alwaysOriginal)
3
4let attachment = NSTextAttachment()
5attachment.image = tinted
6attachment.bounds = CGRect(x: 0, y: -2, width: 14, height: 14)

This is often cleaner than tinting the whole label, because the text and the icon may need different colors.

Multiple Icons or Mixed Formatting

Because the content is an attributed string, you can combine icons, different fonts, and colored text in one label:

1let result = NSMutableAttributedString()
2
3let attachment = NSTextAttachment()
4attachment.image = UIImage(systemName: "flame.fill")?.withTintColor(.systemRed, renderingMode: .alwaysOriginal)
5attachment.bounds = CGRect(x: 0, y: -2, width: 14, height: 14)
6
7result.append(NSAttributedString(attachment: attachment))
8result.append(NSAttributedString(string: " Hot", attributes: [
9    .font: UIFont.boldSystemFont(ofSize: 16),
10    .foregroundColor: UIColor.label
11]))
12
13label.attributedText = result

This is one of the main reasons inline attachments are better than arranging a tiny UIImageView next to a UILabel when the content behaves like a single typographic unit.

When Not to Use an Attachment

If the icon must respond to taps independently, animate separately, or stay perfectly aligned in complex multiline layouts, a combined view hierarchy may still be the better choice. NSTextAttachment is best when the icon is decorative or semantically part of the text.

For example, a badge icon inside a sentence works well as an attachment. A clickable trailing action icon usually does not.

Common Pitfalls

The biggest mistake is forgetting to set attachment.bounds. Without it, the image often appears too large or vertically misaligned relative to the surrounding text.

Another issue is using a full-color image without checking rendering mode. Template images and tinted SF Symbols behave differently from pre-rendered assets, so icon color problems often come from the image configuration rather than from the label.

Finally, test multiline labels carefully. Attachments participate in text layout, but large icons or inconsistent baseline offsets can make line height and wrapping look awkward.

Summary

• Use NSTextAttachment inside an attributed string for inline icons in UILabel.
• Adjust attachment.bounds to control size and baseline alignment.
• Match the icon size to the label font for a cleaner result.
• Tint template images or SF Symbols before attaching them when needed.
• Prefer a separate image view only when the icon needs its own behavior or interaction.