Introduction

In UIKit, gradients are usually implemented with CAGradientLayer, not with a special UIView or UILabel property. For a normal view background, you add the gradient layer behind the content. For label text, you usually mask a gradient with the text shape or use a dedicated gradient-text view.

That distinction matters because gradient backgrounds are straightforward, while gradient text requires layer composition. Treating both as the same problem usually leads to awkward code.

Add a Gradient Background to a UIView

For a plain view background, insert a CAGradientLayer and size it during layout:

1import UIKit
2
3final class GradientViewController: UIViewController {
4    private let gradientLayer = CAGradientLayer()
5
6    override func viewDidLoad() {
7        super.viewDidLoad()
8
9        gradientLayer.colors = [
10            UIColor.systemBlue.cgColor,
11            UIColor.systemTeal.cgColor
12        ]
13        gradientLayer.startPoint = CGPoint(x: 0, y: 0)
14        gradientLayer.endPoint = CGPoint(x: 1, y: 1)
15
16        view.layer.insertSublayer(gradientLayer, at: 0)
17    }
18
19    override func viewDidLayoutSubviews() {
20        super.viewDidLayoutSubviews()
21        gradientLayer.frame = view.bounds
22    }
23}

Updating the frame in viewDidLayoutSubviews is important because the view size can change after rotation or Auto Layout updates.

Wrap the Background Gradient in a Reusable View

If you need the effect in several places, put it in a custom view instead of repeating layer setup in every controller:

1import UIKit
2
3final class GradientBackgroundView: UIView {
4    private let gradientLayer = CAGradientLayer()
5
6    override init(frame: CGRect) {
7        super.init(frame: frame)
8        gradientLayer.colors = [
9            UIColor.systemPink.cgColor,
10            UIColor.systemOrange.cgColor
11        ]
12        layer.insertSublayer(gradientLayer, at: 0)
13    }
14
15    required init?(coder: NSCoder) {
16        super.init(coder: coder)
17        layer.insertSublayer(gradientLayer, at: 0)
18    }
19
20    override func layoutSubviews() {
21        super.layoutSubviews()
22        gradientLayer.frame = bounds
23    }
24}

This keeps controller code cleaner and makes the effect easier to reuse consistently.

Gradient Text for UILabel

UILabel does not have a built-in gradient-text mode. A common solution is to use the label's layer as a mask for a gradient layer:

1import UIKit
2
3final class GradientTextView: UIView {
4    private let gradientLayer = CAGradientLayer()
5    private let label = UILabel()
6
7    override init(frame: CGRect) {
8        super.init(frame: frame)
9
10        gradientLayer.colors = [
11            UIColor.systemPurple.cgColor,
12            UIColor.systemIndigo.cgColor
13        ]
14        layer.addSublayer(gradientLayer)
15
16        label.text = "Gradient Title"
17        label.font = .boldSystemFont(ofSize: 32)
18        label.textAlignment = .center
19
20        addSubview(label)
21    }
22
23    required init?(coder: NSCoder) {
24        fatalError("init(coder:) has not been implemented")
25    }
26
27    override func layoutSubviews() {
28        super.layoutSubviews()
29        label.frame = bounds
30        gradientLayer.frame = bounds
31        gradientLayer.mask = label.layer
32    }
33}

The gradient supplies the color, and the label layer defines the visible text shape.

Why Layout Timing Matters

Gradient text often looks wrong when the mask is applied before the label has its final frame. If the label changes size because of Auto Layout, dynamic type, or text updates, the gradient layer and its mask need to be realigned during layout.

That is why gradient text examples should almost always update in layoutSubviews or another layout-aware point instead of only during initialization.

Common Pitfalls

The biggest mistake is setting the gradient layer's frame once and forgetting to update it when the view bounds change. That breaks gradients after rotation or layout changes.

Another common issue is repeatedly adding new gradient layers during layout, which creates stacking and performance problems. Reuse one layer and resize it.

Developers also expect UILabel to support gradient text directly. It does not. You need masking or a custom drawing approach.

Finally, do not ignore readability. Gradient text can look attractive in a mockup but become hard to read on a real device if the contrast is weak.

Summary

• Use CAGradientLayer for gradients in UIKit.
• For UIView, insert the gradient layer behind the content and resize it during layout.
• For UILabel, gradient text usually requires masking a gradient with the label layer.
• Reusable custom views keep gradient logic cleaner than repeating layer code everywhere.
• Correct layout timing and good contrast matter as much as the gradient colors themselves.