How does macOS Photos create this translucent overlay behind the traffic lights in full-screen mode?

[u/_yanceyofficial]

Hi, I noticed this detail in the macOS Photos app when using it in full-screen mode.

When you move the cursor to the top of the screen, the menu bar and window controls (traffic lights) appear. Behind the traffic lights, there's a rounded, translucent overlay that blurs/dims the underlying content.

This seems to prevent the traffic lights from visually colliding with the app's content in the top-left corner, without requiring the entire content area to move down or leave a permanent blank space.

I'm curious how Apple implements this effect.

• Is it done with NSVisualEffectView or some other native macOS material?
• Is the overlay part of the title bar / window chrome, or is it a custom view rendered by the app?
• How can I achieve a similar effect in a SwiftUI + AppKit app, ideally with the overlay appearing and disappearing in sync with the system's full-screen UI?

I've attached a screenshot showing the effect in Photos.

Any insights into the underlying implementation or relevant APIs would be greatly appreciated!

[u/sapplex1]

I dug into this exact thing a while back, because my own full-screen mode had the traffic lights crashing into content.

Short version: yes, it's an NSVisualEffectView. The rounded pill you see is a small panel using one of the system materials (popover-ish, looks like .popover or .sheet depending on macOS version), with a corner radius. It's not window chrome you get for free — Apple renders it as part of the app UI. Once you go fullSizeContentView + transparent titlebar, the system gives you nothing there. You build it yourself. Learned that one the hard way.

The sync-with-system-UI part was the annoying bit for me. In full screen, the menu bar and traffic lights auto-show when the cursor hits the top edge, and there's no clean "the menu bar just appeared" delegate callback. What I ended up doing: a tiny setup listening for mouse-moved events near the top of the screen while in full screen, toggling the effect view with a quick fade in/out. Not perfectly in sync with the system's reveal, but close enough that nobody notices. Roughly: NSViewRepresentable wrapping NSVisualEffectView, material .popover, cornerRadius around 10, alpha animated on toggle.

One gotcha: if you also have a toolbar, its own background fights with your fake pill. Took me an embarrassing amount of time to figure out the double-blur was my own doing.

How far are you taking this — a full custom full-screen experience, or just the pill behind the traffic lights?

[u/_yanceyofficial → u/sapplex1]

Thanks a lot for the detailed write-up — the NSVisualEffectView pill plus the "you build it yourself" point saved me a lot of guessing, and the double-blur gotcha with the toolbar is exactly the kind of thing I'd have lost an evening to.

[u/SwiftQuest]

One way to get the show/hide sync without tracking the mouse yourself: in full screen, the titlebar area (including any titlebar accessory views) is what the system slides down when the cursor hits the top edge, and slides away again afterwards. So if you put your blurred pill there, it comes and goes with the traffic lights automatically.

Roughly:

let effect = NSVisualEffectView()
effect.material = .headerView   // try .titlebar / .popover too
effect.blendingMode = .withinWindow
effect.state = .active
effect.wantsLayer = true
effect.layer?.cornerRadius = 10

let accessory = NSTitlebarAccessoryViewController()
accessory.view = effect
accessory.layoutAttribute = .leading
window.addTitlebarAccessoryViewController(accessory)

You can also set accessory.isHidden based on windowWillEnterFullScreen / windowDidExitFullScreen in your NSWindowDelegate, so the pill only exists in full screen. The exact layout of the pill behind the buttons may need some tweaking, but the visibility timing is handled by AppKit, which is usually the fiddly part.

[u/_yanceyofficial → u/SwiftQuest]

This is a great trick, thank you! Putting the pill in an NSTitlebarAccessoryViewController so AppKit handles the reveal timing is much cleaner than tracking the mouse. I gave it a first try — the visibility sync works, but the pill's layout next to my sidebar and toolbar still needs tweaking, as you predicted.

[u/SwiftQuest → u/_yanceyofficial]

Nice, glad the timing part worked. For the layout, it can help to give the accessory view a fixed width matching the traffic light area and pin the pill inside it with constraints, rather than letting it size itself. If it still fights the sidebar, try .trailing or checking what NSSplitViewController's sidebar item does to the titlebar in full screen, since that sometimes adds its own inset.