NSCollectionLayoutBoundarySupplementaryItem background blur covering the entire layout section

Question

T. P. OP

Created 1d

Replies 3

Boosts 0

Participants 2

My app has the following UI layout:

NSSplitViewController as the windows contentViewController
- NSPageController in the content (right) split item
  - NSTabViewController as the root items of the NSPageController
    - NSViewController with a collection view in the first tab of that NSTabViewController

The collection view is using a NSCollectionViewCompositionalLayout in which the sections are set up to have a header using NSCollectionLayoutBoundarySupplementaryItem with pinToVisibleBounds=true and alignment=top

With macOS 26, the pinned supplementary item automatically gets a blurred/semi-transparent background that seamlessly integrates with the toolbar. When the window's title bar has a NSTitlebarAccessoryViewController added, the said semi-transparent background gets a bottom hard edge and a hairline to provide more visual separation from the main content.

During runtime, my NSPageController transitions from the NSTabViewController to another view controller. When transitioning back, the semi-transparent blur bleeds into the entire section. This happens no matter if there's a NSTitlebarAccessoryViewController added or not. It doesn't happen 100% of the cases, it seems to depend on section size, header visibility and/or scroll position. But it happens more often than not.

Most of the time, a second or so after the back transition - shortly after pageControllerDidEndLiveTransition: of the NSPageControllerDelegate is called - the view updates and the supplementary views are back to normal. Sometimes, the issue also appears not when transitioning using NSPageController, but simply by scrolling through the collection view.

Anyone has an idea what is happening here? Below are two screenshots of both the "ok" and "not ok" state

Screenshot 2025-10-23 at 14.43.23.png

Screenshot 2025-10-23 at 14.43.25.png

I'm on macOS 26.0.1 and I'm using XCode 26.0.1

Boost

Answer 1

Macho Man Randy Savage OP

20h

Have you inspected the value of clipsToBounds on views in your view hierarchy? Particularly supplementary views.

If the view has clipToBounds set to NO and its -drawRect: uses the dirtyRect it can draw outside its bounds.

0

Answer 2

T. P. OP

18h

My supplementary view is a simple NSView with a centered NSTextField - I don't do custom drawing in drawRect: and setting clipsToBounds to true didn't help. The blur and shade is coming from the NSCollectionView.

One this that seems to mitigate the artifact a bit is to call invalidateLayout on the collectionViewLayout with a 100ms delay in the pageController:prepareViewController:withObject: delegate method of NSPageController - but it's a hacky workaround

0

Answer 3

Macho Man Randy Savage OP

10h

I suggested looking at clipsToBounds b/c I recently ran into a situation that looks very similar to your second screenshot when modifying a project that uses NSCollectionView.

In my case the issue occurred when the layout used a footer view. The footer view implemented drawRect: and was filling the dirty rect. The project was written (not originally by me) but long before clipsToBounds was exposed as public API. Setting clipsToBounds to YES on the footer view stopped the issue from occurring.

It was not my initial thought to check clipsToBounds because all the system blurring mixed in with the semi transparent fill color the footer view used made me think the issue was caused by something else. When I changed the footer view background color to something that stood out more like NSColor.purpleColor it made it more obvious. I first tried all sorts of other tricks. So I figured this story may be worth sharing.

If you are able to narrow your issue down to something else it would be great if you shared here for knowledge building.

0