CSS shape-image-threshold: Wrapping Transparent PNGs

The CSS shape-image-threshold property defines the exact alpha channel boundary used to wrap inline text around non-rectangular images. When paired with shape-outside, it reads the transparency data of a raster image—such as a transparent PNG—and sets an opacity cutoff level. Any pixel with an opacity exceeding this threshold is treated as a solid obstruction, while pixels falling below it allow text to flow through, creating dynamic, contoured text wrapping directly derived from the image's transparent areas.

How the Extraction Mechanism Works

Browsers process transparent PNGs for text wrapping using pixel-level alpha evaluation. Here is the step-by-step mechanism of how the wrapping boundary is formed:

  1. Reading the Alpha Channel: A standard PNG image contains RGB color channels and an alpha channel. The alpha channel stores the opacity level for every individual pixel on a scale from 0 (completely transparent) to 1 (completely opaque), or 0 to 255 in 8-bit representation.

  2. Evaluating the Threshold: The shape-image-threshold accepts a value between 0.0 (or 0%) and 1.0 (or 100%). The browser inspects each pixel in the image specified by shape-outside: url(...).

    • If a pixel's alpha value is strictly greater than the threshold, the browser marks that pixel as part of the shape boundary.
    • If the alpha value is less than or equal to the threshold, the browser marks that area as empty space available for text layout.

  3. Tracing the Contour: Once the pixels are classified as either solid or transparent based on the threshold, the browser's layout engine traces the perimeter of the solid pixel clusters. This creates a mathematical path (a geometric exclusion area) that mirrors the visible silhouette of the graphic.

  4. Reflowing Inline Content: During layout calculation, the browser fits inline text line-by-line around the traced path, applying standard constraints like line height and margin offsets specified by shape-margin.

Threshold Behavior in Practice

The default value for shape-image-threshold is 0.0. Under this default setting, any pixel that is not 100% transparent—even a faint shadow with an alpha of 0.02—will be included inside the exclusion boundary. This often leads to text standing too far away from the visual subject of a PNG that features soft, anti-aliased edges or drop shadows.

By increasing the value (for example, to 0.5), pixels that are more than 50% transparent are discarded from the boundary. This enables the text to tuck tightly against the solid parts of the graphic, ignoring fuzzy, semi-transparent edges and producing a cleaner wrap. Setting the value to 1.0 requires pixels to be completely opaque to exclude text; any semi-transparent pixel will be ignored.

Technical Prerequisites

For shape-image-threshold to extract boundaries from a PNG, the following criteria must be met:

  • Floating Requirement: The element containing the image must be floated (float: left or float: right), as CSS Shapes only affect content flowing around floated elements.
  • Valid Source: The image must be supplied directly to the shape-outside property using a url() value, a CSS gradient, or an SVG data URI.
  • CORS Compliance: Because the browser must read the raw pixel data of the PNG to evaluate the alpha mask, the image must satisfy Cross-Origin Resource Sharing (CORS) rules. If an image is hosted on an external domain without proper Access-Control-Allow-Origin headers, the browser cannot read the pixel data and will fail silently, defaulting back to standard rectangular wrapping.