masksToBounds

masksToBounds is a boolean property of a layer (CALayer) that controls whether the layer’s contents and its sublayers are clipped to the layer’s bounds. When masksToBounds is true, anything drawn outside the layer’s rectangular bounds is not visible; when false, drawing outside may be visible depending on the rest of the layer tree and compositing.

Default value is false. The property is commonly used with cornerRadius to create rounded corners by clipping content to the curved shape. However, enabling masksToBounds also clips shadows and other effects that fall outside the layer’s bounds, which means you typically cannot have both a rounded corner and a visible shadow on the same layer.

A common pattern to preserve both a rounded appearance and a shadow is to use a container approach: one outer layer that draws the shadow and does not mask to bounds, and an inner layer with a cornerRadius and masksToBounds set to clip its content.

In UIKit, the equivalent behavior is provided by UIView’s clipsToBounds property, which maps to the underlying layer’s masksToBounds.

Performance considerations: turning on masksToBounds can trigger offscreen rendering in certain cases, especially with complex sublayers, gradients, or animated content. This can impact rendering performance during animations.

Related concepts: the layer also supports an explicit masking layer via the mask property, which defines arbitrary alpha shapes, whereas masksToBounds provides a simple rectangular clipping to the layer’s bounds.