Introduction

Showing a transparent or semi-transparent UIViewController on top of another controller is a standard iOS technique for overlays, loading masks, dimmed dialogs, and custom modals. The visual effect only works if the presentation style and view backgrounds are configured correctly; otherwise the presenting screen disappears and you see an unexpected black or opaque background.

Choose the Right Presentation Style

If you want the presenting controller to remain visible underneath, do not use the default full-screen replacement behavior. Use either .overCurrentContext or .overFullScreen.

1let overlay = OverlayViewController()
2overlay.modalPresentationStyle = .overCurrentContext
3overlay.modalTransitionStyle = .crossDissolve
4present(overlay, animated: true)

These two presentation styles are similar, but they are not identical:

• '.overCurrentContext presents over the current presentation context'
• '.overFullScreen covers the full screen while still allowing transparency'

In many container hierarchies, .overCurrentContext is the better fit because it respects the current context rather than always targeting the whole screen.

Define the Presentation Context

When using .overCurrentContext, the presenting controller usually needs to declare that it defines the presentation context.

1final class HostViewController: UIViewController {
2    override func viewDidLoad() {
3        super.viewDidLoad()
4        definesPresentationContext = true
5    }
6
7    @IBAction func showOverlay() {
8        let overlay = OverlayViewController()
9        overlay.modalPresentationStyle = .overCurrentContext
10        overlay.modalTransitionStyle = .crossDissolve
11        present(overlay, animated: true)
12    }
13}

Without definesPresentationContext = true, UIKit may choose a different ancestor controller as the presentation context, which often breaks the expected overlay behavior.

Make the Overlay View Transparent

The presented controller must also allow the underlying content to show through. That means the root view should be clear or partially transparent, and any visible content should live in a child container view.

1import UIKit
2
3final class OverlayViewController: UIViewController {
4    private let card = UIView()
5
6    override func viewDidLoad() {
7        super.viewDidLoad()
8
9        view.backgroundColor = UIColor.black.withAlphaComponent(0.35)
10
11        card.backgroundColor = .white
12        card.layer.cornerRadius = 16
13        card.translatesAutoresizingMaskIntoConstraints = false
14        view.addSubview(card)
15
16        NSLayoutConstraint.activate([
17            card.centerXAnchor.constraint(equalTo: view.centerXAnchor),
18            card.centerYAnchor.constraint(equalTo: view.centerYAnchor),
19            card.widthAnchor.constraint(equalToConstant: 240),
20            card.heightAnchor.constraint(equalToConstant: 160)
21        ])
22    }
23}

This produces a dimmed overlay with a white card centered over the original screen. If you want full transparency, set view.backgroundColor = .clear instead.

Dismissing the Overlay

Overlay controllers should still dismiss like any other modal presentation. A tap gesture on the background is a simple approach.

1override func viewDidLoad() {
2    super.viewDidLoad()
3
4    let tap = UITapGestureRecognizer(target: self, action: #selector(close))
5    view.addGestureRecognizer(tap)
6}
7
8@objc
9private func close() {
10    dismiss(animated: true)
11}

If the card itself contains controls, attach the gesture recognizer carefully so taps inside the content area are not swallowed accidentally.

Common Cases Where It Fails

The most common reason transparency does not work is that the presented controller uses .fullScreen or the default automatic presentation style instead of an over-style presentation. In that case, UIKit removes the presenting view from the active visual hierarchy during presentation, so there is nothing visible underneath the new controller.

Another issue is setting only the child view to clear while leaving the root view opaque. The controller's root view is what actually covers the screen, so that background must be configured correctly.

Navigation and tab bar controller hierarchies can also change which controller owns the presentation context. If the wrong controller presents the overlay, the result can look inconsistent even though the overlay code is otherwise correct.

When to Use a Custom Presentation Controller

If the overlay needs custom positioning, interactive dismissal, adaptive behavior, or a background dimming view managed separately from the content, a custom presentation controller may be cleaner than a plain modal overlay. For simple dialogs and loading states, though, .overCurrentContext or .overFullScreen is usually enough.

Common Pitfalls

One pitfall is assuming clearColor alone makes a controller transparent. Transparency only matters if the presentation style keeps the underlying content in place.

Another issue is forgetting definesPresentationContext when using .overCurrentContext. In nested controller setups, that often causes UIKit to present from a higher-level controller than expected.

Developers also get tripped up by iOS presentation defaults. Modern iOS versions may use sheet-style behavior unless you set modalPresentationStyle explicitly.

Finally, be careful with touch handling. A fully screen-sized clear view still intercepts touches unless you deliberately forward or ignore them.

Summary

• Use .overCurrentContext or .overFullScreen to keep the presenting screen visible.
• Set definesPresentationContext = true on the appropriate presenting controller when needed.
• Make the presented controller's root view clear or semi-transparent.
• Put visible content inside a child container view instead of relying on the root view alone.
• If the overlay needs richer behavior, consider a custom presentation controller.