Skip to content
Tutorials Center
My learning

Topics

Lesson 62 of 139 ยท Layout Fundamentals

CSS Shapes

Wrap text around circles, ellipses, polygons and images with shape-outside, add space with shape-margin, and style split inline boxes with box-decoration-break.

Text on the web normally lives in rectangles. Paragraphs are boxes, images are boxes, and when you float an image, the words wrap around an invisible box too. Print designers have never been limited like that: magazines curve text around a round portrait or slant it along a mountain ridge.

CSS Shapes bring that to the browser. With shape-outside you tell a floated element which outline the surrounding text should follow: a circle, an ellipse, a polygon, or even the visible part of an image. This lesson goes deeper than the quick look in the floats lesson. You will learn every shape function, the reference boxes, shape-margin, image-based shapes, and a related property for fragmented inline boxes, box-decoration-break.

The rules of shape-outside

Three facts explain almost every "why isn't my shape working?" question:

  1. It only works on floats. shape-outside changes how inline content wraps around a float. On a non-floated element it does nothing.
  2. It doesn't change how the float looks. The float still paints as a rectangle. If you want the element itself to look round, add border-radius or clip-path too.
  3. It can only shrink the wrap area, never grow it past the float's margin box. The shape is clipped to the float's margin box, so a shape bigger than the element has no extra effect.

The property takes a basic shape function, an image, or a reference box keyword:

CSS
.figure {
  float: left;
  width: 200px;
  height: 200px;
  shape-outside: circle(50%);   /* a basic shape */
  /* shape-outside: url("leaf.png");  an image */
  /* shape-outside: margin-box;       a reference box */
}

Circles and ellipses

circle() takes a radius and an optional center: circle(50% at 50% 50%) is a circle filling a square element. Percentages for the radius are relative to the element's size, so 50% touches the edges of a square.

ellipse() takes two radii, horizontal then vertical: ellipse(45% 50%). The center works the same way, after at.

Moving the center is where things get interesting. A circle centered on the float's outer edge, circle(50% at 0 50%) for a right-floated element, creates a half-moon wrap: the text bulges inward toward the middle of the page.

A round portrait with curved text

The portrait gets its round look from border-radius: 50%, and the text gets its round path from shape-outside: circle(50%). The two are independent, which is exactly why you usually need both.

Polygons

polygon() takes a list of points, each an x and a y coordinate, measured from the top-left corner of the reference box:

CSS
.slope {
  float: right;
  width: 220px;
  height: 320px;
  shape-outside: polygon(100% 0, 100% 100%, 0 100%);
  clip-path: polygon(100% 0, 100% 100%, 0 100%);
}

That is a triangle: top-right, bottom-right, bottom-left. Text starts long at the top and gets shorter as the slope grows. Using the same polygon for clip-path makes the visible shape match the wrap, a pattern you will use again and again.

Points can mix percentages and lengths. Percentages keep the shape proportional when the element resizes; lengths are better for fixed details like a 20px notch.

Text running down a slope

Storing the polygon in a custom property keeps the wrap and the clip in sync: edit it once, and both change.

inset()

inset() describes a rectangle pulled in from each edge, with optional rounded corners: inset(10px 20px round 16px). It's useful when a float has a large margin or padding but you want text to come closer than the box would allow. It's the least dramatic shape, but handy for fine-tuning.

Reference boxes

Every shape is measured against a reference box. By default that's the margin-box, but you can choose another one by writing a keyword after the shape:

Keyword The shape is measured from
margin-box The outer edge of the margin (default)
border-box The outer edge of the border
padding-box The outer edge of the padding
content-box The edge of the content area
CSS
shape-outside: circle(50%) border-box;

A keyword on its own, such as shape-outside: border-box, uses that box's outline, including its border-radius. So a float with border-radius: 50% and shape-outside: border-box wraps text in a circle without writing circle() at all.

shape-margin: breathing room

Text that touches a curve looks cramped. Regular margin doesn't help much, because it pushes the whole rectangle outward, not the curve. shape-margin instead grows the shape itself, keeping the same outline but further out:

CSS
.portrait {
  shape-outside: circle(50%);
  shape-margin: 1rem;
}

Remember the third rule: the result is still clipped to the margin box. If your curve hits the edge of the float, give the float some real margin on the text side too, as the demos above do.

Shapes from images and gradients

shape-outside also accepts an image. The browser looks at the image's alpha channel (its transparency) and wraps text around the parts that aren't transparent. shape-image-threshold sets how opaque a pixel must be to count, from 0 (any visibility at all, the default) to 1 (fully opaque only).

CSS
.leaf {
  float: left;
  width: 240px;
  shape-outside: url("leaf.png");
  shape-image-threshold: 0.4;
  shape-margin: 10px;
}

Image shapes need CORS. The browser reads the image's pixels, so the image must come from the same origin as the page or be served with an Access-Control-Allow-Origin header. Otherwise the shape is silently ignored and the text wraps around the rectangle. Gradients have no such restriction, because the browser draws them itself.

Gradients are images too (see Gradients), so a gradient with a transparent part makes a fine shape. A diagonal gradient that fades from solid to transparent gives you a slanted wrap, and shape-image-threshold picks where along the fade the edge falls:

A shape made from a gradient

Shapes and responsive layouts

A few practical tips:

  • Narrow screens. A 200px float on a 320px-wide phone leaves very short lines. Use a media query or container query to drop the float (and the shape) below a certain width.
  • Old browsers. If shape-outside isn't supported, the text simply wraps around the rectangle. That's a graceful fallback, so you rarely need a feature query.
  • Accessibility. Shapes are purely visual. The reading order and the text itself don't change, so there's nothing extra to do, but decorative floats should be empty or hidden from assistive technology.
  • Don't build layout with it. Shapes are for text wrapping. For arranging boxes, use flexbox or grid.

shape-inside isn't here yet. The opposite idea, making text flow inside a shape, was drafted years ago but no browser supports it. Today you can fake it with two floats, one on each side, each with its own shape-outside.

Shapes deal with how text flows around a box. A related problem is what happens to a box when it gets broken into pieces. An inline element such as a <mark> or <span> can wrap across several lines. By default, the browser treats it as one long strip that was cut into pieces: padding, borders and rounded corners appear only at the very start and the very end, and a background gradient is stretched across all the pieces.

box-decoration-break: clone changes that. Each fragment is drawn as if it were a complete box, with its own padding, border, rounded corners, shadow and background.

CSS
.highlight {
  padding: 0.1em 0.4em;
  border-radius: 6px;
  -webkit-box-decoration-break: clone;
  box-decoration-break: clone;
}
slice versus clone on wrapping highlights

With slice, the right side of the first line has no padding or corner, and the gradient runs across the whole phrase. With clone, every line gets rounded ends, its own shadow and its own full gradient.

The property also applies when a block box is split across pages or columns, for example in print styles or multi-column layout. Firefox and recent Chromium browsers support the unprefixed name; Safari still needs -webkit-box-decoration-break, so write both as shown.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. You add shape-outside with circle(50%) to a <div>, but the text still wraps around a rectangle. What is the most likely cause?

    shape-outside only affects floats. Add float: left or float: right and the text will follow the circle.
  2. 2. A float has shape-outside set to a circle, but it still looks like a square. Why?

    The shape controls where inline content flows. To make the element look round, add border-radius or a matching clip-path.
  3. 3. What does shape-margin do?

    shape-margin expands the shape itself, following its outline. The result is still clipped to the float's margin box.
  4. 4. An image-based shape-outside works locally but is ignored in production, where images come from a CDN on another domain. What is missing?

    The browser must read the image's pixels, which requires the image to be same-origin or served with CORS headers.
  5. 5. Which value makes each line of a wrapped inline highlight get its own padding and rounded corners?

    clone draws every fragment as a complete box. slice, the default, treats the fragments as pieces of one long box.

Summary

  • shape-outside changes the outline that text wraps around, but only on floated elements, and it never changes how the float is painted.
  • Shape functions are circle(), ellipse(), polygon() and inset(); each is measured against a reference box (margin-box by default).
  • Pair shape-outside with border-radius or the same clip-path so the visible shape matches the wrap; a custom property keeps them in sync.
  • shape-margin adds space along the curve; the shape is always clipped to the float's margin box.
  • Images and gradients can define shapes through their transparency; shape-image-threshold picks the cut-off, and image files need CORS.
  • box-decoration-break: clone gives every fragment of a wrapped inline element its own padding, corners, shadow and background.

Next: Centering Anything, the practical guide to centering text, blocks and whole layouts.