Why this happens
UIVisualEffectView is UIKit’s dedicated container for real‑time visual effects such as blur and vibrancy. It does not draw the blurred content itself; instead it samples the layers behind it in the view hierarchy. When you place a UIVisualEffectView inside an image view, the effect samples the image view’s rendered pixels, producing a live blur that updates if the image changes. The key rule from Apple’s documentation: always add your content to the contentView property of the UIVisualEffectView, never directly to the effect view itself.
How to fix it
1. Basic blur overlay on an image view
The simplest approach adds a blur effect view as a subview of the UIImageView. The blur view’s frame must match the image view’s bounds so the effect covers the entire image.
import UIKit
func applyBlur(to imageView: UIImageView, style: UIBlurEffect.Style = .light) {
let blurEffect = UIBlurEffect(style: style)
let blurView = UIVisualEffectView(effect: blurEffect)
blurView.frame = imageView.bounds
blurView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
imageView.addSubview(blurView)
}
Objective‑C equivalent:
- (void)applyBlurToImageView:(UIImageView *)imageView withStyle:(UIBlurEffectStyle)style {
UIBlurEffect *blurEffect = [UIBlurEffect effectWithStyle:style];
UIVisualEffectView *blurView = [[UIVisualEffectView alloc] initWithEffect:blurEffect];
blurView.frame = imageView.bounds;
blurView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
[imageView addSubview:blurView];
}
Why autoresizingMask? It keeps the blur layer sized correctly when the image view resizes (e.g., on rotation or Auto Layout changes).
2. Blur with vibrant text or symbols on top
UIVibrancyEffect ensures that labels, icons, or other content placed above the blur remain legible by dynamically adjusting their color based on the blurred background. The vibrancy view must be a child of the blur view’s contentView.
func applyBlurWithVibrantLabel(to imageView: UIImageView,
text: String,
blurStyle: UIBlurEffect.Style = .dark,
font: UIFont = .systemFont(ofSize: 28, weight: .medium)) {
// 1. Blur layer
let blurEffect = UIBlurEffect(style: blurStyle)
let blurView = UIVisualEffectView(effect: blurEffect)
blurView.frame = imageView.bounds
blurView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
imageView.addSubview(blurView)
// 2. Vibrancy layer (child of blurView.contentView)
let vibrancyEffect = UIVibrancyEffect(blurEffect: blurEffect)
let vibrancyView = UIVisualEffectView(effect: vibrancyEffect)
vibrancyView.frame = blurView.contentView.bounds
vibrancyView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
blurView.contentView.addSubview(vibrancyView)
// 3. Content inside vibrancyView.contentView
let label = UILabel()
label.text = text
label.font = font
label.textColor = .label // vibrancy will override
label.sizeToFit()
label.center = vibrancyView.contentView.center
label.autoresizingMask = []
vibrancyView.contentView.addSubview(label)
}
Objective‑C equivalent:
- (void)applyBlurWithVibrantLabelToImageView:(UIImageView *)imageView
text:(NSString *)text
blurStyle:(UIBlurEffectStyle)style {
UIBlurEffect *blurEffect = [UIBlurEffect effectWithStyle:style];
UIVisualEffectView *blurView = [[UIVisualEffectView alloc] initWithEffect:blurEffect];
blurView.frame = imageView.bounds;
blurView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
[imageView addSubview:blurView];
UIVibrancyEffect *vibrancyEffect = [UIVibrancyEffect effectForBlurEffect:blurEffect];
UIVisualEffectView *vibrancyView = [[UIVisualEffectView alloc] initWithEffect:vibrancyEffect];
vibrancyView.frame = blurView.contentView.bounds;
vibrancyView.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
[[blurView contentView] addSubview:vibrancyView];
UILabel *label = [[UILabel alloc] init];
label.text = text;
label.font = [UIFont systemFontOfSize:28 weight:UIFontWeightMedium];
label.textColor = [UIColor labelColor];
[label sizeToFit];
label.center = vibrancyView.contentView.center;
[[vibrancyView contentView] addSubview:label];
}
3. Blur a portion of an image (mask‑style)
If you only need a blurred region (e.g., a bottom sheet), create a standalone UIVisualEffectView sized to that region and add it above the image view in the same superview, not inside the image view.
func addBlurredOverlay(on view: UIView,
in rect: CGRect,
style: UIBlurEffect.Style = .regular) {
let blurEffect = UIBlurEffect(style: style)
let blurView = UIVisualEffectView(effect: blurEffect)
blurView.frame = rect
blurView.autoresizingMask = []
view.addSubview(blurView)
}
How to prevent it
- Always use
contentViewfor any subviews inside aUIVisualEffectView. Adding directly to the effect view breaks the effect. - Set
autoresizingMaskor Auto Layout constraints so the blur layer resizes with its container. - Reuse the same
UIBlurEffectinstance when creating both the blur and vibrancy effects; they must match. - Avoid stacking multiple blur views — each one triggers an off‑screen render pass and hurts performance.
- Test on device — the simulator’s software renderer can look different from GPU‑accelerated blur on hardware.
FAQ
Can I blur a UIImage directly without a UIImageView?
No. UIVisualEffectView blurs the layer hierarchy behind it. You must place the image in a view (e.g., UIImageView or a CALayer backed view) and put the effect view in front of it.
Why is my vibrancy label invisible?
Ensure the label is added to vibrancyView.contentView, not vibrancyView itself. Also verify the UIBlurEffect passed to UIVibrancyEffect(blurEffect:) is the exact same instance used for the blur view.
Does UIVisualEffectView work in SwiftUI?
Not natively. Wrap it in UIViewRepresentable if you need UIKit blur inside SwiftUI, or use SwiftUI’s .background(.ultraThinMaterial) family of materials for a native alternative.
Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.
