How to Blur an Image with UIVisualEffectView in UIKit

How to Blur an Image with UIVisualEffectView in UIKit

Written by

in

Quick answer: Add a UIVisualEffectView initialized with a UIBlurEffect as a subview of your image view. Set its frame to match the image view’s bounds. For vibrant text on top, nest a UIVisualEffectView with UIVibrancyEffect inside the blur view’s contentView.

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 contentView for any subviews inside a UIVisualEffectView. Adding directly to the effect view breaks the effect.
  • Set autoresizingMask or Auto Layout constraints so the blur layer resizes with its container.
  • Reuse the same UIBlurEffect instance 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.

Sources & credits

Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.