CSS3 shape-outside property

Support for shape-outside

You can create shapes for text (and other stuff) to contour-wrap using the CSS3 shape-outside property. This spec is only supported in newer Chrome, Opera, and Safari (iOS) based browsers. Unfortunately, neither Microsoft Edge nor Internet Explorer currently support this feature (boo-hiss!). And only very recent versions of Firefox support it. To see what which browsers do, in fact, currently support it at the time you read this article, check out caniuse.com.

Progressive Enhancement Approach

The best way to get other browsers to 'get with the program' is to USE stuff you want to see supported. You can easily use shape-outside in a progressive enhancement way because it is predicated on a supported property we use all the time: the 'float'.

You can design your content normally using floats and then add the shape-outside feature as an enhancement. Pretty simple. To see what this page would look like in a graceful degradation mode on non-supporting browsers, look at this page in Firefox or IE.

How Do I Use “shape-outside”?

There are several applications, but let's address the simple stuff first. You can manually create the shape geometry with really easy-to-use shape-outside functions. Some really common methods are:

circle()
ellipse()
polygon()

You can also use some other types of values, and the following are probably the most commonly used:

border-box (useful when defining border-radius)
url() - takes path to transparent png so text can cover transparent areas

Important for iOS/Safari Support!

It is recommended that as you test your work that you look in as many browsers as possible on the caniuse.com page. You will notice that some features require the -webkit- vendor prefix as a separate line first for functionality in Safari. To be safe, you can always include it. If it is unnecessary, the browser will ignore the declaration. You can check to see if a prefix is required in specific browsers for any property on the Mozilla Developer Network (MDN) website by doing a search for the property by name. You'll find the info at the bottom of the page under “Browser Compatibility.” Sometimes caniuse.com won't have the properties you are looking for, but the (MDN) website most likely will because it is very well maintained.

Here's an example of how to write CSS declarations using redundancy with vendor prefixes:

CSS

-webkit-shape-outside: circle();
shape-outside: circle();

NOTE: for the sake of efficiency on this page, vendor prefixes were not included in example code snippets. You will need to add them yourself when testing in Safari.

Start with circle()

Let's do a test starting with a circle-based image. First things first: you need to float your image next to some text, sort of like this:

HTML
<img src="my-circle-image.png" alt="cool picture"> Type a whole bunch of lorem ipsum here....
CSS
img { float: left; width: 30%; margin: 3%; }

At this point you should have a normal looking floated image. Now you can add the code below to get the circle to work. You might need to adjust the margin of <img> depending on how your image looks.

CSS

img {
    float: left; 
    width: 30%; 
    margin: 3%; 
    shape-outside: circle();
}

NOTE: If you need a quick circle-based picture to use just for testing, you can use the value "http://sandbox.leighcotnoir.com/lessons/css-shape-outside/images/circle-pic.png" for the image source attribute above!

Now, onto ellispe()

Using the exact same code base, you can simply do a css adjustment to distort your circular image above into an ellipse (just for testing pursoses). Fix the image dimension in pixels this time and stretch the height to make the image elliptical so that we can also then change the shape-outside function to ellipse(). For the ellipse function to work, you need to pass radius values into it for x and y axes. Try the changes to the code below:

CSS

img {
    float: left; 
    width: 300px; 
    height: 600px; 
    margin: 3%; 
    shape-outside: ellipse(50% 50%);
}

If you want to experiment more, you can read more on additional options with ellipse().

Okay, now let's try polygon()

Even though the image we are working with so far is not a polygon, we can still use it to experiment so we can just keep moving along with the testing.

To start with a simple polygon you always need at least 3 pairs of x/y values to create the vertices for an enclosed object. When considering the values, remember that the coordinate starting position of 0/0 begins in the top left of the image. So as you map the coordinates, think of it as a chart. Let's start off simply by changing the following:

CSS

img {
    float: left; 
    width: 300px; 
    height: 600px; 
    margin: 3%; 
    shape-outside: polygon(0% 0%, 0% 100%, 100% 50%);
}

~ ~ ~

To better understand how the coordinates are being drawn, take a peek at the adjacent diagram (click the image to view it full scale). Look at the coordinate pairs, remembering that the first value is how much we travel to the right on X, while the second value in the pair is how much we travel down on Y to reach the coordinate destination.

Then you can inspect it using the Chrome CSS Shapes plugin and modify for a more complex shape by adding and dragging the vertices interactively on the screen. Rather than reading to understand, watch the following demo:

A polygon() Illustration

Just for fun, this is an example of how the polygon() function can work with the shape-outside property.

Here's a Yoda quote to wrap the picture:

"Ready are you? What know you of ready? For eight hundred years have I trained Jedi. My own counsel will I keep on who is to be trained. A Jedi must have the deepest commitment, the most serious mind. This one a long time have I watched. All his life has he looked away… to the future, to the horizon. Never his mind on where he was. Hmm? What he was doing. Hmph. Adventure. Heh. Excitement. Heh. A Jedi craves not these things. You are reckless."

How do I use “shape-outside: url()”?

The "url()" value allows you to place a transparent png 32 inside the url parameter, so that the browser will automatically wrap text in the transparent areas of the image. It is only supported as of early 2016 in the Safari/iOS and Chrome browsers. Opera, Firefox, and IE offer no support at this time. This is great when it works because you don't have to use complex polygons for complex shapes. Below is sample code you could try:

HTML
<img src="http://sandbox.leighcotnoir.com/lessons/css-shape-outside/images/hummingbird.png" alt="hummingbird"> Type a whole bunch of lorem ipsum here....
CSS
img { float: left; width: 40%; shape-outside: url(http://sandbox.leighcotnoir.com/lessons/css-shape-outside/images/hummingbird.png); }

An illustration of url() in use

Four loko chartreuse street art PBJ yuccie mumblecore 8-bit. Bespoke etsy bitters shabby chic, pop-up tote bag kinfolk williamsburg helvetica poutine readymade fap fixie. hummingbird Austin fap plaid hella pabst fingerstache offal, waistcoat beard gastropub lo-fi. Quinoa crucifix fingerstache tacos, portland swag semiotics cray knausgaard normcore green juice. Occupy taxidermy crucifix craft beer iPhone, aesthetic butcher banh mi. 90's williamsburg chillwave fashion axe, mustache next level chia affogato mumblecore. Fap photo booth squid flexitarian aesthetic, schlitz stumptown.

Master cleanse retro kitsch, migas food truck drinking vinegar 8-bit deep v schlitz banjo cray readymade mumblecore church-key. Lomo listicle banjo, freegan blue bottle cronut pinterest. Bespoke yuccie cardigan, mlkshk four loko kinfolk YOLO PBR normcore sustainable vice crucifix iPhone you probably haven't heard of them sartorial. Knausgaard tumblr photo booth, pour-over portland brunch squid waistcoat VHS food truck gluten-free vegan kale chips. Stumptown taxidermy scenester, hoodie williamsburg selfies bushwick post-ironic fixie portland butcher cornhole. Fixie truffaut helvetica swag ethical. YOLO man braid raw denim, cliche beard tofu 3 wolf moon iPhone bitters ramps messenger bag.

Bespoke yuccie cardigan, mlkshk four loko kinfolk YOLO PBR normcore sustainable vice crucifix iPhone you probably haven't heard of them sartorial. Knausgaard tumblr photo booth, pour-over portland brunch squid waistcoat VHS food truck gluten-free vegan kale chips. Stumptown taxidermy scenester, hoodie williamsburg selfies bushwick post-ironic fixie portland butcher cornhole. Fixie truffaut helvetica swag ethical. YOLO man braid raw denim, cliche beard tofu 3 wolf moon iPhone bitters ramps messenger bag.

Four loko chartreuse street art PBJ yuccie mumblecore 8-bit. Bespoke etsy bitters shabby chic, pop-up tote bag kinfolk williamsburg helvetica poutine readymade fap fixie. Austin fap plaid hella pabst fingerstache offal, waistcoat beard gastropub lo-fi. Quinoa crucifix fingerstache tacos, portland swag semiotics cray knausgaard normcore green juice. Occupy taxidermy crucifix craft beer iPhone, aesthetic butcher banh mi. 90's williamsburg chillwave fashion axe, mustache next level chia affogato mumblecore. Fap photo booth squid flexitarian aesthetic, schlitz stumptown.

Using the “border-box” value

When a border radius is applied to an element, you can also apply “shape-outside: border-box;” to the same element so that adjacent elements will follow the contour of the border-radius. If you want visual space between the float and the adjacent elements, you also need to apply both regular margins as well as the “shape-margin” property. To test this, be sure to use an image whose boundaries are not transparent. Some example code:

HTML
<img src="my-image.jpg" alt="cool picture"> Type a whole bunch of lorem ipsum here....
CSS
img { float: left; width: 40%; shape-outside: border-box; margin: auto 30px 30px auto; shape-margin: 30px; }

An illustration of the “border-box” value in use

dog Four loko chartreuse street art PBJ yuccie mumblecore 8-bit. Bespoke etsy bitters shabby chic, pop-up tote bag kinfolk williamsburg helvetica poutine readymade fap fixie. Austin fap plaid hella pabst fingerstache offal, waistcoat beard gastropub lo-fi. Quinoa crucifix fingerstache tacos, portland swag semiotics cray knausgaard normcore green juice. Occupy taxidermy crucifix craft beer iPhone, aesthetic butcher banh mi. 90's williamsburg chillwave fashion axe, mustache next level chia affogato mumblecore. Fap photo booth squid flexitarian aesthetic, schlitz stumptown.

Syntax

Keyword values

shape-outside: none;
shape-outside: margin-box;
shape-outside: content-box;
shape-outside: border-box;
shape-outside: padding-box;

Function values

shape-outside: circle();
shape-outside: ellipse();
shape-outside: inset(10px 10px 10px 10px);
shape-outside: polygon(10px 10px, 20px 20px, 30px 30px);

url value

shape-outside: url(image.png);

Global values

shape-outside: initial;
shape-outside: inherit;
shape-outside: unset;