Introduction

CATextLayer can render sharp text with low overhead, but default settings often produce blurry output on Retina displays. Most clarity issues come from incorrect layer scale, fractional geometry, or mismatched font configuration. This guide shows a practical setup that keeps text crisp in real iOS layouts.

Set contentsScale and Geometry Correctly

The first requirement is matching the layer rendering scale to device pixel density. Without this, text is drawn at low resolution and then upscaled.

1import UIKit
2
3let textLayer = CATextLayer()
4textLayer.contentsScale = UIScreen.main.scale
5textLayer.frame = CGRect(x: 20, y: 80, width: 280, height: 40)
6textLayer.string = "Sharp text"

Also avoid fractional coordinates when possible. Fractional frame origins can place glyph edges between pixels.

1func alignToPixel(_ value: CGFloat, scale: CGFloat) -> CGFloat {
2    return round(value * scale) / scale
3}
4
5let scale = UIScreen.main.scale
6let x = alignToPixel(20.3, scale: scale)
7let y = alignToPixel(80.2, scale: scale)
8textLayer.frame.origin = CGPoint(x: x, y: y)

These two settings fix most blur complaints.

Configure Font and Size Explicitly

A common mistake is setting fontSize but leaving font details ambiguous. Set both font and fontSize deliberately.

1import CoreText
2
3let font = UIFont.systemFont(ofSize: 18, weight: .medium)
4textLayer.font = font
5textLayer.fontSize = font.pointSize
6textLayer.foregroundColor = UIColor.label.cgColor
7textLayer.alignmentMode = .left
8textLayer.truncationMode = .end

You can also provide a CTFont reference when you need tight control over metrics.

let ctFont = CTFontCreateWithName("HelveticaNeue" as CFString, 18, nil)
textLayer.font = ctFont
textLayer.fontSize = 18

Consistency between font object and point size reduces layout drift and unexpected clipping.

Use Attributed Strings for Better Typography

NSAttributedString gives better control for kerning, paragraph style, and color. This helps when long labels wrap or when center alignment should remain visually balanced.

1let paragraph = NSMutableParagraphStyle()
2paragraph.alignment = .center
3paragraph.lineBreakMode = .byTruncatingTail
4
5let attrs: [NSAttributedString.Key: Any] = [
6    .font: UIFont.systemFont(ofSize: 17, weight: .semibold),
7    .foregroundColor: UIColor.systemBlue,
8    .paragraphStyle: paragraph,
9    .kern: 0.1
10]
11
12textLayer.string = NSAttributedString(
13    string: "Readable CATextLayer title",
14    attributes: attrs
15)

If text looks clipped, increase layer height to account for font ascender and descender values.

Avoid Parent-Layer Settings That Degrade Text

Even a correctly configured CATextLayer can blur if parent layers force rasterization.

containerLayer.shouldRasterize = false
containerLayer.rasterizationScale = UIScreen.main.scale

If you must rasterize for animation performance, ensure rasterization scale matches screen scale and profile visual quality after transforms.

Also watch for transforms like non-integer scaling:

textLayer.setAffineTransform(.identity)

Non-integer scale transforms can soften glyph edges.

Snapshot and Dynamic Type Considerations

If text changes frequently, update layer string on the main thread and avoid recreating layers each frame. For Dynamic Type support, regenerate font settings when content size category changes.

1NotificationCenter.default.addObserver(
2    forName: UIContentSizeCategory.didChangeNotification,
3    object: nil,
4    queue: .main
5) { _ in
6    let newFont = UIFont.preferredFont(forTextStyle: .body)
7    textLayer.font = newFont
8    textLayer.fontSize = newFont.pointSize
9}

This keeps sharpness and accessibility aligned.

Common Pitfalls

• Leaving contentsScale at the default value and expecting Retina-quality rendering.
• Using fractional frame geometry that places text on half pixels.
• Setting only fontSize without matching font.
• Enabling aggressive parent-layer rasterization without checking quality.
• Applying non-integer transforms to text layers during animation.

Summary

• Set contentsScale to UIScreen.main.scale for crisp text rendering.
• Align frames to pixel boundaries to avoid blur from fractional placement.
• Configure both font and fontSize, not one without the other.
• Prefer attributed strings when typography and alignment matter.
• Check parent-layer rasterization and transforms when text still appears soft.