The shape-image-threshold property defines the alpha channel threshold used to extract a CSS Shape applied to an element using an image.
Quick reminder: a CSS Shape can be applied to an element to change the geometry of the element’s float area, thus changing the way the content flows around it. A shape is applied using the shape-outside property. A shape can be defined using either a shape function or a shape image. When an image is used, it must be CORS compatible, and have an alpha channel (e.g a PNG with transparent and opaque areas). The shape-image-threshold defines the threshold of that alpha channel, that is used to extract the shape from the image.
A CSS shape extracted from an image is defined by the pixels whose alpha value is greater than the threshold. For example, a value of 0.5 means that the shape will enclose all the pixels that are more than 50% opaque. Values range between 0.0 and 1.
For more information about using an image to define a CSS Shape and on defining and using CSS Shapes in general and examples of images, please refer to the shape-outside property entry.
Trivia & Notes
A future level of CSS Shapes may define a switch to use the luminance data from an image instead of the alpha data. When this happens, shape-image-threshold will be extended to apply its threshold to either alpha or luminance, depending on the switch state.
Official Syntax
-
Syntax:
shape-image-threshold: <number> - Initial: 0.0
- Applies To: floats
- Animatable: yes, as a number
Values
- <number>
-
A
<number>that sets the threshold used for extracting a shape from an image. The shape is defined by the pixels whose alpha value is greater than the threshold. A threshold value outside the range 0.0 (fully transparent) to 1.0 (fully opaque) will be clamped to this range.
Examples
The following sets the shape image threshold of an image used to define a shape on an element:
.element {
shape-outside: url(shape-image.png) border-box;
shape-image-threshold: 0.2;
}
The following is an example of an image with an alpha channel, than can be used to define a shape on an element.
Refer to the Shape property entry for more.
Live Demo
The following example uses this image to define a shape on the element:
The image contains transparent areas, as well as two shapes, each having a different alpha value. One shape (on the right) is fully opaque, with an alpha value of 1. The smaller shape on the left has an alpha value of 30% (0.3). Play with the value of the shape-image-threshold in the following demo. Try using a value that’s above 30% to see how the lower shape is no longer used as part of the shape.
Browser Support
CSS Shapes Level 1
Allows geometric shapes to be set in CSS to define an area for text to flow around. Includes properties `shape-outside`, `shape-margin` and `shape-image-threshold`
W3C Candidate Recommendation
Supported from the following versions:
Desktop
- 37
- 62
- No
- 24
- 10
Mobile / Tablet
- 10
- 123
- No
- 123
- 124