CSS shape-outside: Guide to Text Wrapping

The CSS shape-outside property allows developers to wrap inline content around non-rectangular, geometric shapes instead of standard rectangular bounding boxes. This article explains the primary purpose of shape-outside, how it fundamentally changes text wrapping in modern web design, and the different methods you can use to define custom wrapping boundaries around floated elements.

The Core Purpose of shape-outside

In standard CSS layout, every element is treated as a rectangular box. Even if an element is visually circular, triangular, or an image with a transparent background, adjacent text treats the element as a rectangle and wraps in a straight vertical line along its boundary.

The shape-outside property breaks this limitation by defining a custom virtual boundary that adjacent inline text must flow around. This brings print-style typography and magazine-like layouts to the web, creating more organic, visually appealing relationships between text and media.

How shape-outside Works

To use shape-outside, an element must meet two prerequisites:

  1. It must be floated using float: left or float: right.
  2. It must have explicit dimensions (a defined width and height).

The property changes only the wrapping area of adjacent inline content; it does not change the element's actual layout, background, or borders. To visually match the element's shape to the text flow, developers typically pair shape-outside with clip-path.

Defining Shapes

The shape-outside property accepts several types of values:

1. Basic Shape Functions

You can use mathematical shape functions to generate precise geometric areas:

  • circle(): Wraps text in an arc or around a full circular radius.
  • ellipse(): Defines an oval boundary with separate horizontal and vertical radii.
  • polygon(): Connects multiple coordinate pairs to create complex multi-sided shapes, such as triangles, diamonds, or custom silhouettes.

2. Image and Alpha Channel Transparency

You can pass an image directly into the property using url(). The browser reads the image's alpha (transparency) channel and flows text tightly against the opaque pixels. This behavior can be fine-tuned with shape-image-threshold, which sets the opacity level required for a pixel to be counted as part of the shape boundary.

3. Box Values

You can define shapes based on standard CSS box-model edges, such as margin-box, border-box, padding-box, or content-box. When paired with border-radius, using margin-box will cause text to follow the curved corners of the element's border radius.

Managing Spacing with shape-margin

Because shape-outside bypasses the standard CSS margin model for the wrapping path, adding a standard margin to the floated element does not create space between the custom shape and the wrapping text. Instead, you use the shape-margin property, which adds an offset buffer directly to the defined shape boundary.