CSS Reference Property

shape-margin

The shape-margin property is used to add a margin to a shape applied to an element using the shape-outside property.

The shape-margin property does not work exactly like the margin property does. They’re identical in that the amount of margin you specify will add extra space between the element and the content around it. But they differ in that the margin of the shape is actually a new shape that is defined as the smallest shape contour that includes all the points that are the shape-margin distance outward in the perpendicular direction from a point on the underlying shape. Note that at points where a perpendicular is not defined (e.g. sharp points) take all points on the circle centered at the point and with a radius of shape-margin.

In other words, the shape-margin property creates a new shape around the shape applied to an element. The new shape is formed by a set of points. The points that make up the margin shape are positioned shape-margin distance outward from every respective point on the original shape.

The best way to explain this is using a visual demonstration. The purple area represents the white space that will be added around the polygonal shape defined in the image. The new shape created using shape-margin is the size of the original shape plus the purple area.

For any point on the main shape where a perpendicular line can be drawn, that perpendicular is drawn (virtually, to define the margin shape) that is shape-margin away from the point outwards, and a corresponding point is defined for the margin shape. For sharp edges where no perpendicular can be drawn, a circle is computed whose center is positioned on the point, and the radius of the circle is set to the value of the shape-margin, and then all the points on the circle that are shape-margin distance outward from the point are used in the margin shape. See the following illustration for a clearer interpretation:

shape-margin-illustration
Image showing a shape contour created using shape-margin.

Trivia & Notes

Note that if the element already has some margin applied to it and then a shape applied using shape-outside, it may or not be necessary to add any extra margin to the shape. The shape is applied to the element using the margin-box as a reference box. If you use any of the other box model’s boxes as a reference box, then the shape-margin will probably be more useful. Please refer to the shape-outside property entry for more information about the reference box and on how to apply and use a CSS Shape.

Official Syntax

  • Syntax:

    shape-margin: <length> | <percentage>
                           
  • Initial: 0
  • Applies To: floats
  • Animatable: yes, as length, percentage, or calc.

Values

<length>
A <length> value. Sets the margin of the shape to the specified value.
<percentage>
A <percentage> value. Sets the margin of the shape to a percentage of the width of the element’s containing block.

Examples

The following is an example adding a shape margin to a shape defined on an element using shape-outside, and using the element’s border-box as a reference box.

.element {
    shape-outside: circle(70% at 0% 50%) border-box;
    shape-margin: 2em;
}
                

The following is a screenshot of the example showing the flow of content around the shape without the added margin, and then after the margin is added.

shape-margin-example
Screenshot of the example showing the flow of content around the shape without the added margin, and then after the margin is added.

See the shape-outside property entry for a live demo and explanation on how to create this example.

Live Demo

The following demo shows the result of adding a margin to a polygonal shape. Play with the values of the shape-margin property.

Note: see the browser support table below for information on whether or not the demo works in your browser or not, and what prefixes you may need to use.

See the shape-outside property entry for the original demo and for an explanation on how to create the shape and apply it.

View this demo on the Codrops Playground

Browser Support

CSS Shapes Level 1

Allows geometric shapes to be set in CSS to define an area for text to flow around.

W3C Candidate Recommendation

Supported from the following versions:

Desktop

  • 37
  • No
  • No
  • 24
  • 7.1*

Mobile / Tablet

  • 8*
  • 56
  • 37
  • 57
  • No

* denotes prefix required.

  • Supported:
  • Yes
  • No
  • Partially
  • Polyfill

Stats from caniuse.com

Further Reading

Written by

Last updated December 11, 2016 at 10:47 pm by Mary Lou

Do you have a suggestion, question or want to contribute? Submit an issue.