CSS shape-image-threshold Property

The shape-image-threshold property controls how a raster image is interpreted when that image is used as a clipping outline or float shape. Rather than using every non-transparent pixel, the property establishes a numeric threshold that determines which pixels of the source image count as "inside" the shape and which count as "outside." In practice this lets authors turn a photo or texture into a usable silhouette by excluding low-opacity or low-luminance pixels so text and other inline content can flow around a clean, predictable contour instead of the image's raw pixel outline.

Under the hood the property is applied per pixel: the image is sampled and each pixel is compared against the chosen threshold using the image’s alpha channel or luminance, depending on how the implementation interprets the image. Pixels that meet the threshold are treated as part of the solid shape; contiguous included pixels are then converted into the final outline used for layout. Because this conversion is derived from raster sampling, results depend on the image’s resolution, scale, and any interpolation or anti-aliasing; a small or heavily compressed image can produce a jagged or imprecise outline, while a high-resolution silhouette yields a smoother, more accurate boundary.

This property is most commonly used together with image-based float shaping, for example when an element’s float region is defined by an image via shape-outside. It affects how surrounding inline content wraps around that float and works hand-in-hand with spacing controls such as shape-margin to tune the distance between the generated outline and adjacent content. Because image-based shapes typically apply to floated elements, it also indirectly interacts with usual float behavior - see float - so the final visual result is a combination of the float placement, the threshold-derived outline, and any margin or offset rules.

Practical use favors images that have clear, high-contrast silhouettes or preparing images so the desired silhouette is explicit (for example, by editing the image to remove stray semi-transparent pixels). Authors should be aware of performance and loading behavior: the browser must decode and sample the image to produce the polygonal outline, which can add cost compared with geometric shapes. Also note that when the image is not available or when an implementation cannot derive a shape, the layout typically falls back to a simpler bounding box or normal float behavior, so designing appropriate fallbacks (or ensuring the image is loaded early) improves robustness.