How to Wrap Text Around Images with CSS shape-outside

The CSS shape-outside property allows web developers to wrap text dynamically around non-rectangular shapes, moving beyond the limitations of standard rectangular bounding boxes. This article explains the primary function of shape-outside, the essential prerequisites for using it, the supported shape functions, and how it transforms text wrapping around images.

The Purpose of shape-outside

In standard web layout, every HTML element is defined by a rectangular box model. When an image is floated to the left or right, surrounding inline text wraps strictly along the outer edges of that rectangular boundary, regardless of whether the image contains transparent pixels, rounded corners, or organic forms.

The shape-outside property solves this limitation by defining a custom geometric shape or extraction path on a floated element. Surrounding inline elements will then reflow and conform to the custom contour rather than the element's traditional box model.

Requirements for Implementation

To make shape-outside work properly, two conditions must be met:

  1. The element must be floated: The target element must have either float: left; or float: right; applied. Non-floated elements will ignore shape-outside.
  2. Explicit dimensions: The element must have defined dimensions, such as a set width and height, to calculate the coordinate space for the shape.

Key Value Types and Functions

Developers can define wrapping boundaries using geometric functions, reference boxes, or image transparency channels:

  • Basic Shape Functions:

    • circle(radius at position): Wraps text around a circular perimeter. For example, shape-outside: circle(50%); wraps text tightly around a round portrait.
    • ellipse(rx ry at position): Generates an oval shape with distinct horizontal and vertical radii.
    • polygon(x1 y1, x2 y2, ...): Creates complex geometric shapes by specifying a sequence of coordinates.
    • inset(top right bottom left): Creates an inner rectangular boundary with optional rounded corners.

  • Image Alpha Channels: By passing an image source directly to the property—such as shape-outside: url('graphic.png');—the browser extracts the shape based on the image's transparency. Developers can fine-tune the boundary using shape-image-threshold, which defines the alpha opacity level used to separate transparent space from solid shapes.

  • Box Values: Using keywords like margin-box, border-box, padding-box, or content-box aligns the text wrapping path to specific layers of the CSS box model, which can be combined with border-radius values.

Adding Spacing with shape-margin

Traditional CSS properties like margin do not control the spacing between text and a custom shape defined by shape-outside. Instead, developers use the shape-margin property. Setting shape-margin: 15px; pushes surrounding text away from the defined shape perimeter, ensuring the typography remains legible and properly spaced from the visual element.