CSS

🖼️ Mastering shape-image-threshold in CSS

📌 What Is shape-image-threshold?

The shape-image-threshold property controls how much of an image's alpha channel (transparency) is used to compute the shape for shape-outside.
It is ONLY used when shape-outside is set to url() or an image-based shape.
In simple words:It determines what parts of an image count as “solid enough” for text to wrap around.

>>“shape-image-threshold adjusts how strict the image silhouette is when wrapping text.”

🧩 Basic Syntax

Syntax

shape-image-threshold: <number>;   /* value between 0 and 1 */

shape-image-threshold: 0;     /* loose threshold */
shape-image-threshold: 0.5;   /* medium cutoff */
shape-image-threshold: 1;     /* strict threshold: only fully opaque pixels count */

✔ Value range: 0 → 1
✔ Higher value = stricter mask
✔ Lower value = softer, more inclusive shape

🎯 How It Works

0 → everything with ANY opacity counts (very soft silhouette)
1 → only fully opaque pixels count (sharp silhouette)
Values in between adjust how aggressively transparent areas are removed

🧪 Example: Image Shape With Soft Silhouette

Threshold 0 (soft)

.shape-soft {
  float: left;
  width: 250px;
  height: 250px;
  shape-outside: url(star.png);
  shape-image-threshold: 0;
  shape-margin: 10px;
  background: url(star.png) center/contain no-repeat;
}

✔ The shape includes even low-opacity areas
✔ Great for soft glow-like silhouettes

🧪 Example: Medium Threshold

Threshold 0.5 (balanced)

.shape-mid {
  float: left;
  width: 250px;
  height: 250px;
  shape-outside: url(blob.png);
  shape-image-threshold: 0.5;
  shape-margin: 10px;
}

✔ Removes lightly transparent pixels
✔ Good for most PNG artwork with soft edges

🧪 Example: Strict α Cutoff

Threshold 1 (sharp edges)

.shape-strict {
  float: left;
  width: 250px;
  height: 250px;
  shape-outside: url(png-shape.png);
  shape-image-threshold: 1;
  background: url(png-shape.png) center/contain no-repeat;
}

✔ Only 100% opaque pixels define the shape
✔ Perfect for hard-edged icons or stencils

🌈 Visual Summary

Threshold	Effect
0	Very soft edges, almost entire image considered solid
0.5	Balanced — medium transparency trimmed
1	Only completely opaque regions used

🔥 Advanced Example: Creating Clearer Wrapping Around an Irregular Shape

Clear silhouette

.leaf {
  float: right;
  width: 300px;
  height: 300px;
  shape-outside: url(leaf.png);
  shape-image-threshold: 0.85;
  shape-margin: 15px;
}

✔ Removes semi-transparent fringes
✔ Produces a much cleaner text wrap

🎨 Combining shape-outside + shape-margin + shape-image-threshold

Full combo

.combo {
  float: left;
  width: 260px;
  height: 260px;
  shape-outside: url(logo.png);
  shape-image-threshold: 0.6;
  shape-margin: 20px;
  background: url(logo.png) center/contain no-repeat;
}

✔ Smooth control
✔ Best for image-based wrapping

🛠️ Best Practices

Use 0–0.4 for soft silhouettes
Use 0.5–0.8 for balanced shapes
Use 0.9–1 for crisp shapes (icons, logos)
Always pair with shape-margin for readability
Use high-quality PNG/SVG with transparency for best results

⚠️ Browser Support

✔ Chrome
✔ Safari
✔ Edge
❌ Firefox does NOT support image shapes (including threshold)

Note

shape-image-threshold only works with image-based shapes, not basic shapes like circle() or polygon().

🔍 Debugging Tips

If text ignores the shape → ensure the element is floated
Set a fixed width + height on the floated element
Adjust threshold until the silhouette feels natural
Check PNG transparency — the alpha channel must exist
Use a temporary clip-path to visualize shape boundaries

🔗 Helpful Tools & Resources

>>“shape-image-threshold lets you sculpt how precisely your text wraps around an image — from soft to razor sharp.” ✨