Shape outside example

Wrapping text around images

The css property shape-outside defines a shape around which text will wrap. Shapes supported by the in-depth framework are circle, ellipse and polygon, and the effect may be applied to an image asset or any Presto asset if an image is configured to replace it.

Using this feature requires familiarity with the browser's web inspector. The basic worksflow is to set shapeOutside to one of the three shape options on an asset in the config editor, which will result in a default value — a starting point — that the producer can edit in the web inspector, manually changing the value of shape-outside on the asset container, along with a few other properties, then copying those values to the config editor. In addition to manually editing the raw value in the inspector, there are shape-outside editors available — natively in Firefox and via the CSS Shapes Editor plugin in Chrome.

The workflow

Use these steps as a tutorial to familiarize yourself with the shapeOutside feature. There are three images for testing listed here, but feel free to substitute your own images on the CDN.

Circle

Target an asset in the config editor. For non-image assets, or to replace an image asset, add an image url:

{asset.12345}
shapeOutside: circle
shapeOutsideImage: https://www.gannett-cdn.com/usat-storytelling/testing/cutouts/baseball.jpg
{}

Reload the page and you'll see that the image is offset to the left of the content well, the text is wrapped around it and a default value has been assigned to shape-outside 1. To view it, hold down the Control key and click on the image, then select "Inspect" from the context menu to reveal the image in the web inspector. The default value of circle(185px at 0% 50%) should now be displayed in the styles panel.

Shape outside controls

The first number in the circle() function refers to the radius of the circle around which the text will wrap, and the two percentages are the x and y coordinates of the circle from the top-left of the container.
The image can be positioned using two CSS variables: --shape-outside-offset-x and --shape-outside-offset-y. The default x value for circle is -175px. Click on the value in the style inspector panel 2 and use the up and down arrow keys to change it and observe the effect. Do the same for the y offset, keeping in mind that the only text that will wrap is that which comes after the image element in the DOM.
To adjust the size of the image, find the style rule of --shape-outside-image-width: 350px 3, click on the value, then use the up and down arrow keys to change the number. Use a combination of image width and the offsets to size and position the image where you want it. Doing so will mean the shape-outside value needs to be adjusted. To activate the visual editor in Firefox, click on the icon next to shape-outside: 4. In Chrome, select the image element in the inspector, then choose "Shapes" from the "»" menu at the top of the style panel (This assumes you have the plugin installed), then click on the arrow cursor icon next to the value for shape-outside. Drag the handle in the middle 5 to position the circle and drag the side handle (Firefox 6) or corner handles (Chrome) to resize it.
Hover over the <img> tag in the inspector and you'll see that it has a right-margin of 2em. This value is the maximum amount of space you can have between you're image and the wrapping text. To increase the value, set shapeOutsideMargin to a larger value in the config editor.
Once you're happy with everything, copy the values you changed from the inspector to the config editor:
shapeOutside: The value of shape-outside
shapeOutsideImageWidth: The value of --shape-outside-image-width.
shapeOutsideOffsetX: The value of --shape-outside-offset-x.
shapeOutsideOffsetY: The value of --shape-outside-offset-y.
shapeOutsideMargin: The value of --shape-outside-margin.

Ellipse

Change shapeOutside to ellipse and change the image name from "baseball.jpg" to "football.jpg". Editing an ellipse works the same as a circle with the exception that the radius value in the ellipse() function is now two values: height and width.

Shape outside ellipse

Polygon

Caution

IMPORTANT: Start with the default value for shape-outside. It uses percentages. If you don't use percentages for polygons, you will have a bad time.

A polygon involves a little more work. Sizing and positioning the image are the same, but the default polygon will need to have points added and positioned.
Change shapeOutside to polygon in the config editor and change the filename to "golfclubs.jpg". This image should be positioned on the right side of the content well, so set shapeOutsidePosition to right in the config editor and reload.
To add a point in Firefox, double-click on the path; double-click again on the handle to remove it (single clicks in the Chrome plugin). Remember to switch between the desktop and mobile views to be sure the polygon work in both. Open a preview of the page and change the width of the window in the desktop view, looking for any odd wrapping. Adjust as necessary, and when you're satisfied, copy the values to the config editor. Congratulations! You just wrapped text around a polygon!

Shape outside ellipse

Options

option	purpose	required	default
`shapeOutside`	Activates the `shape-outside` feature on the targeted asset or replacement image.	Yes	`circle`
`shapeOutsideImage`	An image on the CDN.	No

Wrapping text around images

The workflow

Circle

Ellipse

Polygon

Options

Examples