A view that adds translucency and vibrancy effects to the views in your interface.


When you want views to be more prominent in your interface, place them in a visual effect view. The visual effect view is partially transparent, allowing some of the underlying content to show through. Typically, you use a visual effect view to blur background content, instead of obscuring it completely. The visual effect view can also make its contained content more vibrant to ensure that it remains prominent.


A visual effect view provides two different styles of translucency, as illustrated in the screenshot:

  • Behind-window blending allows whatever is behind the window to show through. This style is automatically set in many places, including sheets, pop-overs (NSPopover), and table views using the source list selection highlight style.

  • In-window blending allows the window content to show through, and is automatically set for toolbars.

Vibrancy is associated with translucency. It describes a compositing mode that does special blending such as Plus Lighter, Plus Darker, Color Dodge, or Color Burn. The system automatically uses vibrancy in many places, including popovers, sheets, and sidebar table views. Some UI elements dynamically use vibrancy based on their contents. For example, an NSTextField object uses vibrancy when certain special colors are used, such as NSColor’s labelColor and secondaryLabelColor. You may, though, need to support vibrancy in a custom view, or conversely you may need to disable vibrancy in a view.

Managing Vibrancy

The first step in supporting vibrancy in a view is to contain the view in an instance of NSVisualEffectView. It is typically best to add vibrancy only to leaf views, not container views, because it is difficult to turn vibrancy off once it is on. In addition:

  • The view must implement allowsVibrancy to return true.

  • The view’s effective appearance must allow vibrancy (i.e. it must be either the vibrantLight or vibrantDark appearance).

    In most cases you set the appearance on the window or on the visual effect view—subviews then inherit the appearance.

  • If the blending mode is withinWindow, the view must use Core Animation layers.

    In this case it is best to set wantsLayer to true on the parent view that contains the visual effect view, because blurring will occur with visual effect view and its subviews.

By default, if a view is set to be drawn as vibrant, both it and all of its subviews will be vibrant—a subview can not turn off vibrancy simply by returning false from allowsVibrancy. Whether or how you can turn off vibrancy depends on the blending mode—this is because NSVisualEffectView’s implementation of blurring and vibrancy itself depends on the blending mode:

  • In behind-window blending, the system describes a rectangle that should be blurred to the window server. Areas that should be vibrant are also described in a similar way. In this situation, you can opt-out rectangular shapes by adding another visual effect view with its state set to inactive; you then add subviews to that.

    Note that adding another visual effect view will make the rectangle containing the view non-vibrant, including anything drawn in that rectangle by the parent view. This may have the effect of showing up as darker or lighter rectangles around some views. The only solution in this case is for the entire view either to be vibrant or non vibrant. You can’t mix the two.

  • With in-window blending, vibrancy is achieved by setting the layer’s compositing filter. The compositing filter applies to the layer and all its children, that means a child view will always be vibrant. However, you can add non-vibrant sibling views over the vibrant view; the overlapping sibling views will not be vibrant.

Using Appearances

You can optionally set the appearance to vibrantDark or vibrantLight to get the desired light or dark appearance. You can combine this with an appropriate light or dark material to get the desired vibrant look. Do not combine NSAppearanceNameVibrantDark with a light material because the resulting effect looks bad.

Subclassing Notes

If you subclass NSVisualEffectView:



var interiorBackgroundStyle: NSView.BackgroundStyle

The view’s interior background style.

var blendingMode: NSVisualEffectView.BlendingMode

Specifies how the view’s contents are blurred.

var state: NSVisualEffectView.State

Specifies the view’s visual effect state.

var maskImage: NSImage?

The view’s image mask.


enum NSVisualEffectView.Material

Constants to specify the material the visual effect view uses.

enum NSVisualEffectView.BlendingMode

Constants to specify the source of content for blending that the visual effect view uses.

enum NSVisualEffectView.State

Constants to specify how the material appearance should reflect window activity state.

Instance Properties


Inherits From

See Also

Visual Adornments

class NSBox

A stylized rectangular box with an optional title.