CSS Shapes (shape-outside): Wrap Text Around Custom Shapes

CSS Shapes let you control how inline content wraps around floated elements. With shape-outside, you can make text flow around circles, ellipses, polygons, or image-based outlines instead of only wrapping around a rectangle.

Quick answer: shape-outside changes the wrap area for a floated element. It does not clip the element itself or move the text by force; it only affects how surrounding content flows around the float.

Difficulty: Intermediate

You'll understand this better if you know: basic CSS layout, how floats affect document flow, and how box model measurements like width, height, and margin work.

1. What Is CSS Shapes?

CSS Shapes are a set of CSS features that let text and inline content wrap around a shape rather than a simple rectangle. The most important property is shape-outside, which defines the wrapping boundary for a floated element.

It changes the area that nearby inline content can flow around.
It works with floated elements, not normal block-level layout.
It supports built-in shapes such as circles, ellipses, and insets.
It can also use an image alpha channel to define the wrapping edge.

In practical terms, CSS Shapes are useful when you want magazine-style text wrapping or a more polished editorial layout.

2. Why CSS Shapes Matter

Standard floats wrap text around a rectangle. That is often fine, but it can look awkward when you place text beside photos, avatars, illustrations, or decorative artwork. CSS Shapes help the layout feel more natural and visually balanced.

They matter because they improve presentation without requiring extra markup or image editing. You can create cleaner layouts directly in CSS, which keeps design changes flexible and maintainable.

Use CSS Shapes when you need controlled text flow around a floated element. Do not use them when you only need basic left-right image alignment, because simpler layout patterns are easier to maintain.

3. Basic Syntax or Core Idea

The basic idea is simple: float an element, then define the wrapping shape with shape-outside. Most shape functions also need the float to have a size, and many designs use shape-margin to add breathing room.

Minimal example with a circle

This example wraps text around a circular float.

.circle {
  float: left;
  width: 160px;
  height: 160px;
  shape-outside: circle(50%);
  shape-margin: 1rem;
}

The float makes the element participate in text wrapping, width and height give the shape a visible box, and shape-outside changes the wrapping contour from rectangular to circular.

4. Step-by-Step Examples

Example 1: Wrapping around a circular photo

A common use case is a portrait image with text wrapping around it. The shape is circular, but the image itself can remain a square or be clipped separately.

.portrait {
  float: left;
  width: 220px;
  height: 220px;
  shape-outside: circle(50%);
  shape-margin: 1rem;
  border-radius: 50%;
}

This combination gives the visual impression of a round photo while also making the text follow the same curve.

Example 2: Using an ellipse for wider content

If the float is wider than it is tall, an ellipse often looks better than a circle.

.feature-box {
  float: right;
  width: 280px;
  height: 180px;
  shape-outside: ellipse(45% 40% at 50% 50%);
  shape-margin: 12px;
}

The ellipse creates a softer wrap than a rectangle and keeps the spacing consistent around a wide object.

Example 3: Wrapping around a custom polygon

For decorative or angled designs, polygon() gives more control over the outline.

.diagonal-shape {
  float: left;
  width: 240px;
  height: 240px;
  shape-outside: polygon(
    0% 0%,
    100% 0%,
    70% 100%,
    0% 100%
  );
  shape-margin: 0.75rem;
}

This is useful when the text should follow a slanted image edge or another custom contour.

Example 4: Using an image-based shape

You can also use the alpha channel of an image to define the wrapping boundary. Transparent pixels are ignored, so the visible opaque area becomes the shape.

.shape-from-image {
  float: left;
  width: 260px;
  height: 260px;
  shape-outside: url("shape-mask.png");
  shape-margin: 1rem;
}

This technique is powerful for editorial art direction, but it requires the right image format and careful asset preparation.

5. Practical Use Cases

CSS Shapes are most useful in layouts where text should visually follow a non-rectangular object. Common situations include:

Magazine-style article layouts with images embedded inside paragraphs.
Author bios where text wraps around a circular portrait.
Landing pages with decorative illustrations beside copy.
Product pages where descriptive text flows around a promo graphic.
Education or news sites that want a more polished editorial feel.

They are a design enhancement, not a requirement for normal content flow. If the page works well without them, keep the simpler layout.

6. Common Mistakes

Mistake 1: Forgetting to float the element

shape-outside only affects floated elements. Beginners often add the property and expect the text to wrap, but nothing changes because the element is still in normal flow.

Problem: Without float, the browser ignores the wrapping shape for surrounding inline content.

.box {
  width: 200px;
  height: 200px;
  shape-outside: circle(50%);
}

Fix: Add a float so the browser knows the element should influence text wrapping.

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

The corrected version works because floated elements create a wrap boundary that shape-outside can modify.

Mistake 2: Expecting the element itself to become circular

shape-outside does not clip or visually reshape the element. It only changes how text flows around it. If you want the element to look round, you need a separate visual property such as border-radius or a mask.

Problem: This code changes the wrapping area, but the element still looks like a square box.

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

Fix: Add matching visual styling when the shape should also appear round.

.avatar {
  float: left;
  width: 180px;
  height: 180px;
  shape-outside: circle(50%);
  border-radius: 50%;
}

The fix works because the wrapping shape and the visible shape now match.

Mistake 3: Using an invalid size or missing dimensions

Shape functions are based on the float box. If the element has no usable size, the resulting wrap area may be unexpected or ineffective. This is especially common when developers forget to set both dimensions for a shape-driven float.

Problem: The float has no defined size, so the browser cannot build the shape you expect.

.shape {
  float: left;
  shape-outside: ellipse(50% 40%);
}

Fix: Give the floated element an explicit size so the shape has a box to reference.

.shape {
  float: left;
  width: 240px;
  height: 180px;
  shape-outside: ellipse(50% 40%);
}

The corrected version works because the browser can now calculate the wrapping boundary from the element’s box.

7. Best Practices

Use shape-margin to keep text readable

Text that hugs a complex shape too closely becomes hard to read. A small margin makes the layout feel deliberate instead of cramped.

.wrapped-figure {
  float: left;
  width: 200px;
  height: 200px;
  shape-outside: circle(50%);
  shape-margin: 0.75rem;
}

This helps avoid awkward collisions between the text and the float.

Keep the visual shape and wrap shape consistent

If the wrapped area is circular but the visible object is a rectangle, the layout may feel confusing. Matching them improves clarity.

.rounded-photo {
  float: right;
  width: 220px;
  height: 220px;
  shape-outside: circle(50%);
  border-radius: 50%;
}

When the visible shape matches the wrap shape, readers understand the layout more quickly.

Prefer simple shapes before using image-based outlines

Image-based shapes are flexible, but they are harder to maintain and more likely to create cross-browser or asset-pipeline issues. Start with circles, ellipses, insets, or polygons when they can express the same design.

.simple-wrap {
  float: left;
  width: 180px;
  height: 180px;
  shape-outside: inset(10% 10% 10% 10% round 1rem);
}

Simple shapes are easier to reason about and usually easier to debug.

8. Limitations and Edge Cases

shape-outside only affects floated elements, so it does not replace modern layout systems like flexbox or grid.
The shape is based on the float’s box, so the element needs explicit, predictable dimensions in most real layouts.
It changes text wrapping, not clipping or masking. If you need the content itself to be shaped, use other CSS features.
Browser support is good in modern browsers, but older browsers may ignore the shape and fall back to normal rectangular float wrapping.
Image-based shapes depend on the image’s alpha channel and the browser’s ability to read the resource correctly.
Responsive layouts can shift the wrap dramatically if the floated box changes size at different breakpoints.

If shape-outside seems to have no effect, the first thing to check is whether the element is actually floated and whether it has a usable size.

9. Practical Mini Project

Here is a complete small example: a profile intro with text flowing around a circular portrait. This is the sort of layout where CSS Shapes feel natural and useful.

<article class="profile-card">
  <img class="profile-photo" src="photo.jpg" alt="Portrait of a designer">
  <p>
    Maya is a product designer who writes about accessible interfaces, content-first
    layouts, and visual consistency. Her articles often combine strong typography with
    subtle motion and clear interaction patterns.
  </p>
  <p>
    She works with teams that need interfaces to feel polished without sacrificing speed
    or maintainability.
  </p>
</article>

.profile-card {
  max-width: 700px;
  font: 1rem/1.6 system-ui, sans-serif;
}

.profile-photo {
  float: left;
  width: 180px;
  height: 180px;
  shape-outside: circle(50%);
  shape-margin: 1rem;
  border-radius: 50%;
  object-fit: cover;
  margin: 0 1rem 1rem 0;
}

This example works because the image is floated, sized predictably, and given both a visual shape and a wrap shape. The surrounding text follows the curve instead of a box, which makes the layout feel more intentional.

10. Key Points

shape-outside controls how content wraps around a floated element.
It does not clip the element or change its visual outline by itself.
Most useful shapes are circle(), ellipse(), inset(), polygon(), and image-based outlines.
Always set a float and a reliable size before expecting the shape to work.
shape-margin is important for readable spacing.
Use CSS Shapes for editorial layouts, not for everyday alignment.

11. Practice Exercise

Try building a short article block that wraps text around a floating shape.

Create a floated box that is 200px by 200px.
Make the wrapping area circular with shape-outside.
Add shape-margin so the text does not touch the edge.
Include at least two paragraphs of text beside the shape.
Change the shape from circle() to inset() and observe the difference.

Expected output: The text should flow in a curved path around the float, with consistent spacing between the letters and the shape.

Hint: If nothing changes, check the float first. Without float, shape-outside will not affect the wrap area.

Solution:

<div class="exercise-wrap"></div>
<p>This paragraph should flow around the floated shape in a smooth curve.</p>
<p>A second paragraph helps you see how the wrapping behaves across multiple lines.</p>

.exercise-wrap {
  float: left;
  width: 200px;
  height: 200px;
  shape-outside: circle(50%);
  shape-margin: 1rem;
  background: #d7e7ff;
  border-radius: 50%;
}

This solution shows the minimum pieces needed for CSS Shapes to work correctly in a real layout.

12. Final Summary

CSS Shapes, especially shape-outside, let you create richer text wrapping than the default rectangular float behavior. They are best used for editorial and decorative layouts where the wrap shape is part of the design, not just a technical detail.

To use them successfully, remember the core requirements: float the element, give it a clear size, define the shape, and add spacing when needed. Once you understand that shape-outside changes wrapping rather than visual clipping, the feature becomes much easier to apply correctly.

For a next step, try combining CSS Shapes with responsive images and a few layout breakpoints so you can see how the wrapping changes across screen sizes.