CSS shape-outside: Wrapping Text Around Custom Shapes

shape-outside is a CSS property that redefines the wrapping area around a floated element, so surrounding text flows along a circle, polygon, or even the visible pixels of an image instead of hugging a plain rectangle. Floats have always pushed text around a box; shape-outside lets that box be almost any shape you can describe.

Why floats alone aren’t enough

A floated element — an image, a pull-quote, a decorative shape — always reserves a rectangular area, even if the element itself looks round or irregular. Float a circular avatar and the text next to it still wraps as if the avatar were a square, leaving an awkward triangular gap in the corners. shape-outside fixes that by telling the browser “the actual wrapping boundary is this shape,” independent of the element’s visual box.

This only affects how inline content wraps around the floated element. It doesn’t change the element’s own size or clip its content — for that you’d reach for clip-path, which is a natural pairing with shape-outside since matching the two makes the visible shape and the wrap boundary line up exactly.

Basic shape functions

shape-outside accepts the same basic shape functions as clip-path:

.avatar {
  float: left;
  width: 200px;
  height: 200px;
  shape-outside: circle(50%);
  clip-path: circle(50%);
}

• circle(radius at position) — a circular wrap boundary, commonly circle(50%) for a perfect circle matching a square box.
• ellipse(rx ry at position) — an elliptical boundary for non-square proportions.
• polygon(x1 y1, x2 y2, ...) — an arbitrary straight-edged shape defined by a list of coordinate pairs, useful for angled cutouts, chevrons, or diagonal text wraps.
• inset(top right bottom left) — pulls the wrap boundary inward from the element’s edges, effectively adding asymmetric margin on the side text wraps against.

Coordinates in polygon() are relative to the element’s box (or a specified reference box like margin-box, border-box, padding-box, or content-box), so a shape stays correctly positioned as the element resizes.

Wrapping around an image’s silhouette

The more striking use of shape-outside is deriving the shape from an actual image:

.portrait {
  float: right;
  width: 320px;
  shape-outside: url("/portrait-silhouette.png");
  shape-image-threshold: 0.5;
  shape-margin: 16px;
}

The browser reads the image’s alpha channel and computes a wrap boundary from the opaque pixels — text flows around the subject’s actual outline rather than the image’s rectangular frame. shape-image-threshold sets the alpha cutoff (0 to 1) that counts as “opaque” for this purpose, and the image must be served with CORS headers permitting it to be read for shape computation if it’s cross-origin. This works best with images that have a transparent background around the subject; a fully opaque rectangular photo produces a rectangular shape, defeating the point.

shape-margin

shape-margin adds a buffer between the computed shape and the text that wraps around it, playing the same role margin plays for a normal float — without it, text can sit uncomfortably close to a curved or angled edge.

Requirements and limits

A few constraints are easy to trip over:

• shape-outside only affects floated elements. Set float: left or float: right; without a float, the property has no visible effect.
• It only reshapes the wrap boundary for surrounding inline content — the floated element’s own box, background, and border are unaffected. Combine with clip-path if you also want the element visually clipped to match.
• Image-based shapes need a loaded, same-origin (or CORS-enabled) image. Cross-origin images without the right headers silently fail to produce a shape.
• Browser support is solid in modern engines, but always verify the actual wrap behavior visually — a shape that looks right in a design tool can still produce cramped or overlapping text once real content flows into it.

Animating and responding to shapes

shape-outside values can respond to layout changes the same way any other CSS value can — inside a media query, a container query, or alongside a CSS custom property that’s toggled by a class. A common pattern is swapping a polygon() shape for a plain rectangle (or removing shape-outside entirely) on narrow viewports, since text wrapping around a small angled cutout in a narrow column tends to produce cramped, awkward line breaks rather than the intended effect:

.pull-quote {
  float: right;
  width: 240px;
  shape-outside: polygon(0 0, 100% 20%, 100% 100%, 0 80%);
}

@media (max-width: 600px) {
  .pull-quote {
    float: none;
    shape-outside: none;
  }
}

Dropping the float entirely on narrow screens, rather than just clearing the shape, is usually the safer choice — a floated element with no meaningful room for text to wrap into just produces an oddly placed box with no visual benefit.

Debugging shape boundaries

Because the shape only affects wrapping and not rendering, it’s easy to end up with a mismatch between what’s visible and where text actually wraps — especially with polygon() coordinates that don’t quite match the element’s visual edges. Most browser dev tools expose a shape editor in the layout inspector for elements with shape-outside set, letting you drag control points and see the wrap boundary update live rather than guessing at coordinates and reloading. Setting a temporary outline or background color on the floated element while tuning coordinates also makes the mismatch between the visual box and the computed shape easy to spot at a glance.

When to reach for it

shape-outside is a good fit for editorial layouts: pull quotes with an angled edge, a portrait that text wraps around like a magazine spread, or a decorative polygon breaking up a wall of prose. It pairs naturally with responsive images — see responsive images with srcset and sizes for serving the right resolution to the same element you’re now also shaping — and with object-fit and object-position for controlling how that image fills its box before the shape is even computed.

It’s not a general-purpose layout tool. For grid-based or component layouts, flexbox and grid remain the right choice; shape-outside solves one specific problem — text flow around a floated shape — and doesn’t replace modern layout systems for anything else.

The takeaway

shape-outside redraws the wrap boundary around a floated element as a circle, polygon, ellipse, or the silhouette of an image, instead of the element’s default rectangle. It requires a float to have any effect, pairs well with clip-path when the shape should also be visible, and shape-margin keeps wrapped text from crowding the edge. Use it for editorial-style layouts where text flowing around an irregular shape adds polish — not as a substitute for flexbox or grid in ordinary page layout.