Introduction

TextKit renders inline images by treating them as text attachments inside an attributed string. The key object is NSTextAttachment: once it is embedded in the attributed text, the image flows with the surrounding text instead of sitting in a separate image view.

The Core Idea: Use NSTextAttachment

A text attachment is the standard way to place non-text content inline.

1import UIKit
2
3let attachment = NSTextAttachment()
4attachment.image = UIImage(systemName: "star.fill")
5
6let attributed = NSMutableAttributedString(string: "Rating ")
7attributed.append(NSAttributedString(attachment: attachment))
8attributed.append(NSAttributedString(string: " 5/5"))

That gives you one attributed string where the image participates in the text flow.

Display It in a Text View or Label

Once the attributed string is built, assign it to a UIKit text-rendering view.

textView.attributedText = attributed

For simpler cases, the same concept works with a label that supports attributed text.

label.attributedText = attributed

A text view is usually the better fit when the content is longer, scrollable, or interactive.

Adjust the Attachment Bounds

The raw image size often needs adjustment so it aligns visually with the text baseline.

let attachment = NSTextAttachment()
attachment.image = UIImage(systemName: "paperclip")
attachment.bounds = CGRect(x: 0, y: -3, width: 16, height: 16)

The y offset is commonly tweaked so the icon sits more naturally with surrounding text.

Build Mixed Content in One Attributed String

Inline images are easiest to manage when the whole text block is built as one mutable attributed string.

1let result = NSMutableAttributedString(string: "Attach ")
2result.append(NSAttributedString(attachment: attachment))
3result.append(NSAttributedString(string: " a file before sending"))
4textView.attributedText = result

This keeps text and inline media in one layout system instead of trying to manually position separate views.

TextKit Still Owns Layout

The useful design point is that TextKit still handles wrapping, line breaking, and container layout. You are not calculating pixel positions for the image by hand. You are giving TextKit an attachment and letting the layout manager place it inside the text flow.

That is what makes attachments more robust than overlaying a small image view near a label and hoping the layout holds across font sizes.

Keep Attachment Sizes Close to Text Size

Inline images usually look best when they are sized intentionally for the surrounding font. If the attachment is much larger than the text, line height and visual rhythm start to feel uneven even though the code technically works.

Treat the image like typography, not like a standalone illustration.

Prefer Attachments Over Manual Layout Hacks

If the image is conceptually part of the sentence, keeping it inside the attributed string is usually more durable than trying to synchronize separate text and image views by hand. TextKit already knows how to reflow content when fonts, widths, or accessibility settings change.

Common Pitfalls

The biggest mistake is trying to fake inline images by placing separate image views next to labels. That does not behave like real flowing text.

Another issue is forgetting to resize or vertically offset the attachment, which makes the image look misaligned relative to the text baseline.

A third problem is using images that are too large for the surrounding font and expecting TextKit to guess the intended visual scale.

Summary

• Use NSTextAttachment to insert images inline with attributed text.
• Append the attachment into a mutable attributed string.
• Display the result in a UITextView or an attributed UILabel.
• Adjust attachment.bounds so the image aligns visually with the text.
• Let TextKit handle line wrapping and layout instead of positioning separate image views manually.