adobe-webplatform / css-shapes-polyfill

Polyfill for the CSS Shapes Specification

shapes-polyfill

The shapes polyfill is a JavaScript implementation of the CSS Shapes specification. You can use the polyfill to approximate CSS Shapes behavior in browsers that do not support the feature. By default, the polyfill will not run when a native shapes implementation is available.

Using the polyfill

To use the polyfill, download or build shapes-polyfill.js or shapes-polyfill.min.js (the minified version). Then, include it in your page:

<script src='/shapes-polyfill.js'></script>

After that, set any shape styles in <link> or <style> stylesheets accessible to your domain:

.shape {
    float: left;
    shape-outside: circle(50%);
    shape-margin: 1em;
}

And add the required markup:

<div class='shape'></div>
This is some content that will wrap around the floating
shape to the left. How very exciting!

That's it!

Customization

By default, the script runs automatically. You can disable this behavior by setting data-auto-run to false on the script tag.

<script src='/shapes-polyfill.js' data-auto-run='false'></script>

The polyfill can also be run on-demand using the run method:

<script>
    window.onload = function() {
        window.ShapesPolyfill.run();
    }
</script>

If you are going to re-run the polyfill, you should first call teardown:

<script>
    window.setInterval(function() {
        window.ShapesPolyfill.teardown();
        window.ShapesPolyfill.run();
    }, 5000);
</script>

Optional parameters can be passed in a params object to the run method, including force which can be set to one of the ShapePolyfill.Force values to force style reload, layout, or both. You might want to use this approach if you are dynamically modifying styles, or want to control exactly when the polyfill runs. For an example, check out tests\shapes-performance.html.

Building the Polyfill

If you are interested in tinkering with the polyfill, you will need the following build dependencies:

• node,
• npm, and
• grunt

To build

1. Clone the source code
2. From the command line, enter the source directory
3. Run npm install
4. Run grunt build

If you are successful, you should have an updated shapes-polyfill.js and shapes-polyfill.min.js in your source directory. For a full list of tasks, just enter grunt at the command line.

The main source files are in the src directory, and you should make sure that any modifications you make pass the test suite in tests\shape-test-suite.html. Note that some of the tests require being run from a local server.

Known Issues

The polyfill isn't perfect, and will generally work best with simple shapes. If you find a bug, please log an issue to let us know.

• Because of the way styles are loaded, inline styles, and those added after the script is loaded, will not be added automatically.
• The implementation works by creating a series of floats approximating the shape's contour and parenting them within a zero-height div. As such, it may introduce line breaks if the original float shape occurs in the middle of a line of text.
• Multiple shaped floats stacking or in close proximity may clear each other once the polyfill is applied.
• The polyfill is slower than native implementations doing shapes layout (roughly 10-20x). You should take this into consideration when deciding if the polyfill is right for your project.
• IE does not support SVG image values, as its security model prevents grabbing rendered SVG pixel values via canvas.
• Some browsers will not issue a CORS request if a non-CORS version of the resource has already been loaded. This may surface if you use the same image as an img' src and shape-outside.

Browser Support

The polyfill should work with all current versions of desktop and mobile browsers. Below is a table of support for Chrome (C), Firefox (FF), Internet Explorer (IE), Opera (O), Safari (S), Android (A), and iOS (iOS) browsers.

<th>A</th>
<th>iOS</th>

<td>2.1</td>
<td>3.2+</td>

C	FF	IE	O	S
5+	4+	10+ [1]	12+	5+

[1] If you are not using cross-origin images, the polyfill should work back to IE 9. Also note the lack of SVG support, as of IE 11.

Feedback

Please let us know if you have any feedback. If you run into any problems, you can file a new issue. You can also reach us @adobeweb.

css-shapes-polyfill's Issues

An error occurred loading a stylesheet, probably because we can't access the local file system

I have this problem. I don't know why
"An error occurred loading a stylesheet, probably because we can't access the local file system"

The container gets too big for shape-outside: padding-box when border is applied.

<style>
    .container {
        width: 800px;
    }

    .shape {
        float: left;
        padding: 20px;
        border: 21px solid  yellow;
        width: 80px;
        height: 80px;
        -webkit-shape-outside: padding-box;
    }
</style>
</head>
<body>
<div class="container"><div class="shape"></div>
<p>Pelicans are a genus of large water birds comprising the family Pelecanidae. They are characterised by a long beak and large throat pouch used for catching prey and draining water from the scooped up contents before swallowing. They have predominantly pale plumage, the exceptions being the Brown and Peruvian Pelicans. The bills, pouches and bare facial skin of all species become brightly coloured before the breeding season. The eight living pelican species have a patchy global distribution, ranging latitudinally from the tropics to the temperate zone, though they are absent from interior South America as well as from polar regions and the open ocean. Fossil evidence of pelicans dates back at least 30 million years, to the remains of a beak very similar to that of modern species recovered from Oligocene strata in France.
</div>
<script src='../shapes-polyfill.js'></script>

with polyfill:

native:

Also border is painted on the top of the content.

The polyfill should respect margin-box

Currently the this test fails:

css-shapes-polyfill/tests/shape-info-tests.js

Line 47 in 6dbafa4

name: 'for margin-box',

Polyfill will occasionally hide shape-outside floats

Setting the z-index to -1 will occasionally hide the float's content.
For example, if the shape-outside float and the body both have different background colors.

including shapes-polyfill.js in wordpress

dear developers,

thanks for your great work.
i would like to include the shapes-polyfill.js in wordpress. i put it in the footer.php of my theme, it does not work properly. it seems that the script is not answering, so i must stop manually.

browser in use is ff 38.0.5

downloaded demos from your platform are looking well, there are no javascript-problems.

i would be very pleased, if you could help.

thank you so much.

regards
willy-george

Does not work when floating one shape to the left, and a second to the right, in Firefox.

Appears in Firefox 37.0.1. Seems to comply with the Known Issues section: "Multiple shaped floats stacking or in close proximity may clear each other once the polyfill is applied."

shape-outside: margin-box with padding fails

bff2ede

Inset on the margin-box + (padding & border & margin) fails

82102b3

shape-outside: content-box with padding wraps around padding box

Failing test case:
ae11b97

5 tests fail on IE 11

On IE 11.0.7

Simple Shape CSS Values

• shape-outside
• shape-margin
• shape-image-threshold
• shape-outside, shape-margin, shape-image-threshold
• embedded with other rules

Tests fail.
Error message: Access is denied.

Does not work when shape-rules are nested in @media queries

Example:

@media (max-width: 767px) {
  .wrap {
    shape-outside: url(...);
  }
}

Expected: The polyfill will respect the media-query and re-calculate the shape when the media-query is in use.

Actual: Error attempting to run querySelectorAll on @media ...: shapes-polyfill.js#L1379

A script on this page may be busy, or it may have stopped responding. You can stop the script now, open the script in the debugger, or let the script continue.

Hi Team,

am getting this issue 'A script on this page may be busy, or it may have stopped responding. You can stop the script now, open the script in the debugger, or let the script continue.' and css polyfill is not working

querySelectorAll in Firefox, syntax error

Hi, I used code like it was specified in readme:

<p> <img class="shape" src="hubert-photo.png" /> Blablabla (...) blablabla </p>

.shape
{
   border-radius: 50%;  /* gives  circle */
   float: right;
   shape-outside: circle(50%);
   shape-margin: 1em;
}

Tried in Firefox 47, and Palemoon 27, both give error in console:
"SyntaxError: An invalid or illegal string was specified" in line 1379 of the not-minified source:

        new StylePolyfill(function(rules) {
            rules.forEach(function(rule) {
                var els = document.querySelectorAll(rule.selector);     // <------- here
                for (var i = 0; i < els.length; i++)
                    els[i].setAttribute('data-' + rule.property, rule.value);
            });

By inspecting variables I see els is undefined. So querySelectorAll didn't return anything.

The rule variable contains:

property: "shape-outside"
selector: "*/.shape"
value: "circle(50%)"

The querySelectorAll doesn't work with this selector syntax. Do you know why? Is that Firefox specific limitation?

If I change selector to ".shape" then the js doesn't break, querySelectorAll returns proper node. I don't see the script working as intended but it might be due to many things.

Anyway, is the removal of */ a good workardound? Where is the */ added in the file? I can't find it.

Wrapping content between two shapes fail in Microsoft Edge

When using the technique described in the "Alice in Wonderland" example (https://www.html5rocks.com/en/tutorials/shapes/getting-started/#toc-inside-shape among other), this fails in Microsoft Edge and Firefox.

Works in IE 11 and Chrome

Experience Firefox and Microsoft Edge

Experience IE 11 and Chrome 57

Example code (from the demo set)
simple-shape-outsides.html.txt

It doesn't support shape-inside property

I test it with shape-inside property but it doesn't work.
Do you think to implement it?

Thanks for your work!

Bower or Nodejs support

Would be nice to have these available for both.